Releasing 2.0.2 into master

.github/workflows/release-drafter.yml

@@ -11,6 +11,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Drafts your next Release notes as Pull Requests are merged into "master"
-      - uses: toolmantim/release-drafter@master
+      - uses: toolmantim/release-drafter@v5.6.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/unit-tests.yml

@@ -15,13 +15,17 @@ jobs:
     container:
       image: atk4/image:${{ matrix.php }} # https://github.com/atk4/image
     strategy:
+      fail-fast: false
       matrix:
         php: ['7.2', '7.3', 'latest']
     steps:
-      - uses: actions/checkout@v1
-      # need this to trick composer
+      - uses: actions/checkout@v2
       - run: php --version
-      - run: "git branch develop; git checkout develop"
+
+      # need this to trick composer that this is a "atk4/core:develop" dependency to install atk4/data
+      - name: Rename HEAD to develop for Composer
+        run: git switch -C develop HEAD
+
       - name: Get Composer Cache Directory
         id: composer-cache
         run: |

docs/Dockerfile

@@ -0,0 +1,17 @@
+FROM  python:2-stretch as builder
+
+WORKDIR /www
+
+ADD requirements.txt .
+
+RUN pip install  pip==9.0.1 wheel==0.29.0 \
+    && pip install -r requirements.txt
+
+ADD . .
+
+RUN make html
+#RUN cp -R images build/html/images
+
+FROM  nginx:latest
+
+COPY --from=builder /www/build/html /usr/share/nginx/html

docs/README.md

@@ -1,19 +1,9 @@
-How to build this documentation
+Our documentation can now be built in the Docker.
 
 ```
-sudo apt-get install python-sphinx python-setuptools
-sudo easy_install pip
-
-sudo pip install sphinx_rtd_theme
-sudo pip install sphinxcontrib-phpdomain
-
-make html
+docker build -t docs .
+docker run -p 8080:80 docs
 ```
 
-next open `html/index.html` in your browser
-
-```
-open html/index.html
-```
-
+Open http://localhost:8080/ in your browser.
 

docs/docs.rst

@@ -0,0 +1,43 @@
+================
+Writing ATK Docs
+================
+
+New users of Agile Toolkit rely on documentation. To make it easier for the
+maintainers to update documentation - each component of ATK framework comes
+with a nice documentation builder.
+
+Writing ATK Documentation
+=========================
+
+Open file "docs/index.rst" in your editor. Most editors will support
+"reSTructured Text" through add-on. The support is not perfect, but it works.
+
+If you are updating a feature - find a corresponding ".rst" file. Your editor
+may be able to show you a preview. Modify or extend documentation as needed.
+
+See also: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+Building and Testing Documentation
+==================================
+
+Make sure you have "Docker" installed, follow simple instructions in
+"docs/README.md".
+
+Integrating PhpStorm
+--------------------
+
+You can integrate PhpStorm build process like this:
+
+.. figure:: images/doc-build-phpstorm1.png
+   :scale: 50 %
+   :alt: Create build configuration for the Dockerfile
+
+
+.. figure:: images/doc-build-phpstorm2.png
+   :scale: 50 %
+   :alt: Adjust Port settings to expose 80 as 8080
+
+.. figure:: images/doc-build-phpstorm3.png
+   :scale: 50 %
+   :alt: Use "Ctrl+R" anytime to build docs
+

docs/factory.rst

@@ -16,21 +16,33 @@ things like:
 
 Thanks to Factory trait, the following code::
 
-   $view->add(['Button', 'A Label', 'icon'=>'book', 'action'=>My\Action::class]);
+   $button = $app->add(['Button', 'A Label', 'icon'=>'book', 'action'=>My\Action::class]);
 
 can replace this::
 
    $button = new \atk4\ui\Button('A Label');
    $button->icon = new \atk4\ui\Icon('book');
    $button->action = new My\Action();
+   $app->add($button);
 
+Type Hinting
+------------
+
+Agile Toolkit 2.1 introduces support for a new syntax. It is functionally
+identical to a short-hand code, but your IDE will properly set type for
+a `$button` to be `class Button` instead of `class View`::
+
+    $button = Button::addTo($view, ['A Label', 'icon'=>'book', 'action'=>My\Action::class]);
+
+The traditional `$view->add` will remain available, there are no plans to
+remove that syntax.
 
 Class Name Resolution
 =====================
 
 Ability to specify only name of the class in ATK is used to keep code clean::
 
-   $app->setLayout('Centered');
+   $app->initLayout('Centered');
    $form = $app->add('Form');
    $form->addField('food_selection', ['Lookup', 'model'=>Model\Food::class]);
 
@@ -40,7 +52,7 @@ various methods are able to accept short identifiers for a simple syntax.
 
 .. php:method:: normalizeClassName($name, $prefix = null)
 
-So App::setLayout() would call `normalizeClassName($layout, 'atk4\ui\Layout')`,
+So App::initLayout() would call `normalizeClassName($layout, 'atk4\ui\Layout')`,
 and View::add() would call `normalizeClassName($view, 'atk4\ui')` and finally
 Form::addField() would call `normalizeClassName($field, 'atk4\ui\FormField` to
 produce the actual name of the class.
@@ -49,11 +61,11 @@ ATK also fully supports the following two alternative forms::
 
    use MyOwn\Layout;
 
-   $app->setLayout(Layout::class);
+   $app->initLayout(Layout::class);
 
 and::
 
-   $app->setLayout(new MyOwn\Layout());
+   $app->initLayout(new MyOwn\Layout());
 
 In the first case `Layout::class` resolves into string `"MyOwn\Layout"` by the
 PHP and normalizeClassName would leave it alone. In the former case, object is
@@ -69,31 +81,31 @@ classes defined in global namespace::
    class TestLayout {
    }
 
-   $app->setLayout(TestLayout::class);
-   // same as $app->setLayout('TestLayout');
+   $app->initLayout(TestLayout::class);
+   // same as $app->initLayout('TestLayout');
 
 In this case, the call to normalizeClassName would proceed to prefix 'TestLayout' layout
 into `\atk4\ui\Layout\Test`.
 
-The solution in this case is to use `$app->setLayout('\TestLayout')`
+The solution in this case is to use `$app->initLayout('\TestLayout')`
 
 Name Resoluion Safety
 ---------------------
 
 While you specify name of the layout yourself, it is not a problem, but if
 you have a code like this::
 
-   $app->setLayout($_GET['layout']);
+   $app->initLayout($_GET['layout']);
 
 Although it seems harmless, technically argument can point to ANY class, which
 will be loaded and code in this class executed. This can be solved by using
 a '.' prefix in front of the relative class name::
 
-   $app->setLayout('.'.$_GET['layout']);
+   $app->initLayout('.'.$_GET['layout']);
 
    // or 
 
-   $app->setLayout('.Centered');
+   $app->initLayout('.Centered');
 
 Sub-namespaces
 --------------
@@ -103,12 +115,12 @@ Sometimes developers prefer to use sub-namespaces, so instead of
 to use `\atk4\ui\Layout\Centererd\Login`. This becomes another problem
 for the resolution::
 
-   $app->setLayout('Centered\Login');
+   $app->initLayout('Centered\Login');
 
 This actually looks like the a string generated by `use Centered; Login::class`
 and to avoid, the following syntax can be used::
 
-   $app->setLayout('Centered/Login');
+   $app->initLayout('Centered/Login');
 
 Substituting / Overriding classes
 ---------------------------------

docs/hook.rst

@@ -30,26 +30,28 @@ The framework or application would typically execute hooks like this::
 
 You can register multiple call-backs to be executed for the requested `spot`::
 
-    $obj->addHook('spot', function($obj){ echo "Hook 'spot' is called!"; });
+    $obj->onHook('spot', function($obj){ echo "Hook 'spot' is called!"; });
 
 Adding callbacks
 ================
 
-.. php:method:: addHook($spot, $callback, $args = null, $priority = 5)
+.. php:method:: onHook($spot, $fx = null, array $args = [], int $priority = 5)
 
 Register a call-back method. Calling several times will register multiple
 callbacks which will be execute in the order that they were added.
 
 Short way to describe callback method
 =====================================
 
-There is a concise syntax for using $callback by specifying object only.
+There is a concise syntax for using $fx by specifying object only.
+In case $fx is omitted then $this object is used as $fx.
+
 In this case a method with same name as $spot will be used as callback::
 
     function init() {
         parent::init();
 
-        $this->addHook('beforeUpdate', $this);
+        $this->onHook('beforeUpdate');
     }
 
     function beforeUpdate($obj){
@@ -67,20 +69,20 @@ hook with priority 1 it will always be executed before any hooks with priority
 Normally hooks are executed in the same order as they are added, however if you
 use negative priority, then hooks will be executed in reverse order::
 
-    $obj->addHook('spot', third,    null, -1);
+    $obj->onHook('spot', third,    [], -1);
 
-    $obj->addHook('spot', second,   null, -5);
-    $obj->addHook('spot', first,    null, -5);
+    $obj->onHook('spot', second,   [], -5);
+    $obj->onHook('spot', first,    [], -5);
 
-    $obj->addHook('spot', fourth,   null, 0);
-    $obj->addHook('spot', fifth,    null, 0);
+    $obj->onHook('spot', fourth,   [], 0);
+    $obj->onHook('spot', fifth,    [], 0);
 
-    $obj->addHook('spot', ten,      null, 1000);
+    $obj->onHook('spot', ten,      [], 1000);
 
-    $obj->addHook('spot', sixth,    null, 2);
-    $obj->addHook('spot', seventh,  null, 5);
-    $obj->addHook('spot', eight);
-    $obj->addHook('spot', nine,     null, 5);
+    $obj->onHook('spot', sixth,    [], 2);
+    $obj->onHook('spot', seventh,  [], 5);
+    $obj->onHook('spot', eight);
+    $obj->onHook('spot', nine,     [], 5);
 
 
 .. php:method:: hook($spot, $args = null)
@@ -96,8 +98,8 @@ will be placed in array and returned by hook()::
         return $a+$b;
     };
 
-    $obj->addHook('test', $mul);
-    $obj->addHook('test', $add);
+    $obj->onHook('test', $mul);
+    $obj->onHook('test', $add);
 
     $res1 = $obj->hook('test', [2, 2]);
     // res1 = [4, 4]
@@ -112,7 +114,7 @@ As you see in the code above, we were able to pass some arguments into those
 hooks. There are actually 3 sources that are considered for the arguments:
 
  - first argument to callbacks is always the $object
- - arguments passed as 3rd argument to addHook() are included
+ - arguments passed as 3rd argument to onHook() are included
  - arguments passed as 2nd argument to hook() are included
 
 You can also use key declarations if you wish to override arguments::
@@ -123,8 +125,8 @@ You can also use key declarations if you wish to override arguments::
         return pow($a, $power)+$pow($b, $power);
     }
 
-    $obj->addHook('test', $pow, [2]);
-    $obj->addHook('test', $pow, [7]);
+    $obj->onHook('test', $pow, [2]);
+    $obj->onHook('test', $pow, [7]);
 
     // execute all 3 hooks
     $res3 = $obj->hook('test', [2, 2]);
@@ -151,13 +153,13 @@ Remember that adding breaking hook with a lower priority can prevent other
 call-backs from being executed::
 
 
-    $obj->addHook('test', function($obj){
+    $obj->onHook('test', function($obj){
         $obj->breakHook("break1");
     });
 
-    $obj->addHook('test', function($obj){
+    $obj->onHook('test', function($obj){
         $obj->breakHook("break2");
-    }, null, -5);
+    }, [], -5);
 
     $res3 = $obj->hook('test', [4, 4]);
     // res3 = "break2"
@@ -176,7 +178,7 @@ value is set it may call normalization hook (methods will change $value)::
         $this->data[$field] = $value;
     }
 
-    $m->addHook('normalize', function(&$a) { $a = trim($a); });
+    $m->onHook('normalize', function(&$a) { $a = trim($a); });
 
 Checking if hook has callbacks
 ==============================

docs/index.rst

@@ -20,7 +20,7 @@ Object Containers
 .. figure:: images/containers.png
    :scale: 50 %
 
-Within your application / framework you can quite often have requirement for
+Within your application or framework you can quite often have requirement for
 using containers:
 
  - Form containing fields
@@ -134,8 +134,8 @@ and triggering callbacks::
 
     $object = new AnyClass();
 
-    $object->addHook('test', function($o){ echo 'hello'; }
-    $object->addHook('test', function($o){ echo 'world'; }
+    $object->onHook('test', function($o){ echo 'hello'; }
+    $object->onHook('test', function($o){ echo 'world'; }
 
     $object->hook('test');
     // outputs: helloworld
@@ -273,3 +273,4 @@ Others
 
     debug
     session
+    docs

docs/requirements.txt

@@ -1 +1,2 @@
 sphinxcontrib-phpdomain
+sphinx_rtd_theme

examples/test2.php

@@ -17,7 +17,7 @@ public function doWork()
 }
 
 $c = new MyClass();
-$c->addHook('afterWork', function () {
+$c->onHook('afterWork', function () {
     echo "HOOKed on work\n";
 });
 $c->doWork();