.. Copyright (C) ALbert Mietus, SoftwareBeterMaken.nl; 2016. Part of Pathways project -*- coding: utf-8 -*-

Cobblestone vs Widget
=====================

When a gate to a WebApp is made, one can use both :class:`Widget`\s and :class:`Cobblestone`\s to *define* the :class:`Put`. But what is the difference?

Currently, there is a trivial difference: A :class:`Cobblestone` is available for all kinds of :class:`Put`\s, whereas
the :class:`Widget` is only available for a :class:`WebPut`.

.. note:: This may change in a future release however, as there is nothing “Web”-specific to a Widget.

* A Widget is kind of a PUT. It not really a :term:`PUT`, but it can be considered as mini (or partial) PUT. Whereas the
  :term:`Cobblestone` is more like a :term:`Brick`: a box with functions that can be called and work on te PUT (or
  Widget).

* The functions within a cobblestone are (typically) automatically available for the PUT; the user (the ATS, or a real
  brick) doesn’t need to know in where it is located::

     # The add() function, located in the “math” cobblestone, add can be used directly
     calc.add()

* A Widget has a name. Which should be use explicit before the functionality of that part ca be used::

     # To login, you have to select the “session page” (a Widget) and login there
     ses = calc.widget('Session')
     ses.login()

* Both a Cobblestone and a Widget are objects; so the can save state in ``self``.
* Both are automatically instantiated during the creation of a PUT.

  - a widget can look for its gate via ``self.parent`` (currently the parent is always the PUT, but that may change, as
    widgets can contain sub-widgets
  - a cobblestone can access it PUT by ``self.put``, directly.



Bricks vs Cobblestone
=====================

A :term:`Brick` is closer to a tester then an :term:`Cobblestone`. A test is build out of steps, which itself are build
of smaller steps; by combining those small steps in a logical “function”; the :term:`Brick` becomes reusable. But
principally every tiny step within a brick could be done oen for one; manually if needed. The steps in a :term:`Brick` a
conceptual, those in a :term:`Cobblestone` more technical, and closer to the :term:`PUT`.

By example: To add-up two numbers on a calculator, one has to enter the first number, the ‘+’ operator and the second
number, etc. However, entering a number has smaller steps: one has to press a button digit by digit! That kind of detail
is not essential is most tests. And hidden by “automating” it.

How to press button for butten exactly, is closely related to the :term:`PUT`: on a web-calculator one has to move the
mouse around and “click” on the GUI-parts that represent the keys. But on a old-fashioned desk calculator, one really
has to move physical button. Besides, pressing those buttons is not related to the “add-up-test”. For all other
calculations it is exactly the same. So, that part is usually automated inside the :term:`gate`, with
:term:`Cobblestone`\s.

But automating how to perform an addition-test is quite generic: add the two numbers and verify the result. Typically
that result does not depend on the :term:`PUT`. When a tester needs to automate it --so (s)he can use it a a step in a
bigger test-- it is normally done in a :term:`Brick`.

.. note:: This is no exact border where to “automate it”; it more an art (or stye) then a science.

  The “automation” of splitting a number into digits can be seen a *generic*, for any brand of calculator, both
  physical, as wel for GUI- and web-app.

  At the same time, it is *specific* and closely related to “calculators”. After all, the same add-up test can be used
  to tests “computing servers”. They typically require the complete number (or more), in a xmlrpc, SOAP or other
  message. When one what to both xmlrpc-calculators and web-calculators, one can decide that is all very specific to the
  web-calculator and put most “automation” inside a :term: calculator.

.. tip:: One should stive to a balance. When everything ends up at the same place and that become messy, brick it up
         into the available layers. At the same time, when a simple thing is divided into several places, it there is no
         cohesion, and once should collect it to ‘the right place’.

An pragmatic seperation between :term:`Cobblestone` and :term:`Brick` is “conceptual accessibility”.  All (tiny) steps
within a :term:`Brick` should (conceptually) be possible from a test(er) point of view. Within a :term:`Cobblestone`,
there is more (technical) implementation freedom. So, when a ‘internal function’ or constant is needed within the
:term:`PUT` or: :term:`Gate` is needed, it should be implemented in a :term:`Cobblestone`!


.. caution::  The examples which come with Partways are small! But they use a variety of solutions and layers to
              introduce (show, teach) them. But don’t follow them as an example to brick everything up into very small
              chunks.