CommandBase Class
*****************
Base class for all commands that exist in BasisCore and present common functionalities used in rendering engine.
For list of commands, see :doc:`builtin-commands`

.. note::

   All attributes declared in this class, accessible in child class, but all of them isn't usable in all commands.
   For example :py:attr:`name` attribute in :doc:`source/dbsource` is :py:attr:`required`, but in :doc:`renderable/print` is :py:attr:`optional`.

.. code-block:: html
   :caption: Structure of CommandBase
   :linenos:

   <basis core="" id="" name="" if="" run="" >
    ...
   </basis>

or

.. code-block:: html
   :caption: Structure of void CommandBase
   :linenos:

   <basis core="" id="" name="" if="" run="" />


.. versionadded:: 3.0  Added :class:`id`, :class:`if`, :class:`runat` properties.

Attributes
==========

core :class:`string` :class:`required`
   Determine type of command like :doc:`renderable/print` or :doc:`renderable/list`.
   For example see :ref:`Create-Simple-Command`.

id :class:`string` :class:`optional`
   Use this property for set unique identifier for command.
   The :class:`id` use only in debugging or some advanced case.
   Default value is :class:`null`.
   For example see :ref:`Create-Simple-Command`.

name :class:`string` :class:`optional` :class:`[##-notation`
   Use this property for set name for command.
   This attribute for some commands like :doc:`source/source` is :class:`required`.
   Default value is :class:`null`.
   For example see :ref:`Create-Simple-Command`.

if :class:`string` :class:`optional` :class:`[##-notation` :class:`expression`
   The boolean :doc:`expression` to determine that command can be execute or not.
   Default value is :class:`true`.
   For example see :ref:`Simple-Conditional-Execution` ,and :ref:`Complex-Conditional-Execution`.

run :class:`enum` :class:`optional` :class:`[##-notation`
   Determine side of executing command.
   Default value is :class:`atserver`.
   For more information see :doc:`../enums/run`
   For example see :ref:`Create-Simple-Command`.

.. note::

   For see more Information about :class:`[##-notation`, see :doc:`../[-sharp-sharp-notation`

Example
=======
For learn how to create and run BasisCore Code, see :doc:`/get-start`.

.. _Create-Simple-Command:

Create Simple Command
---------------------
In this example we create simple :doc:`renderable/print` command for learn how to use command in document body.

.. note::

   For more information about :class:`print` command, see :doc:`renderable/print`.


first add :class:`basis` tag to document:

.. code-block:: html
   :linenos:

   <basis>
   </basis>

Then add :class:`core` attribute with some value.
In this example we go to create a :doc:`renderable/print` command:

.. code-block:: html
   :linenos:

   <basis core="print">
   </basis>

In next step, add meaningful :class:`name` and :class:`id`.

.. code-block:: html
   :linenos:

   <basis core="print" id="print-cmd-test" name="test-print">
   </basis>

As mentioned previously, This two properties for some commands like :doc:`renderable/print` is optional and can be omitted.
To run command in client browser set :class:`run` attribute like this:

.. code-block:: html
   :linenos:

   <basis core="print" id="print-cmd-test" name="test-print" run="atclient">
   </basis>

At last,add :doc:`renderable/print` command specific elements like :class:`face` tag and :class:`datamembername` attribute.
complete command is:

.. code-block:: html
   :linenos:

   <basis core="print" id="print-cmd-test" name="test-print" run="atclient" datamembername="db.test-data" >
      <face>
         <h1>@title</h1>
      </face>
   </basis>

.. _Simple-Conditional-Execution:

Simple Conditional Execution
----------------------------

In this example we go to display :class:`if` attribute functionality by using :doc:`expression`.

.. note:: 
   
   For simplicity, we remove unnecessary part of command in this example.

Suppose we have a :class:`print` command and want to add conditional rendering to it. 
In our example client request :class:`query string` contain :class:`do-print` key with either :class:`true` or :class:`false` value.
Value of :class:`do-print` determine that :class:`print` command must be execute or not.

.. code-block:: html
   :linenos:

   <basis core="print" if="[##cms.query.do-print##]" >
      [...]
   </basis>

In above example, in :class:`query string` contain somethings like :class:`do-print=true`, 
value of :class:`if` set to :class:`true` and this expression interpreted as true boolean value.
So :class:`if` evaluation is :class:`true` and :class:`print` command executed.
But for :class:`di-print=false` value of :class:`query string`, evaluation is :class:`false` and command not executed.

.. note:: 

   Any type of boolean expression supported in :class:`if`. for example, all below expression is valid:

   * 1+1 > 2
   * (12/3) <= 5
   * [##cms.form.agree##] = true
   * '[##cms.form.pass]' = '[##cms.form.confirm-pass##]'

   It Also possible to use :class:`AND`, :class:`OR` , :class:`NOT` and :class:`()` for create complicated boolean expression:
   
   * [##cms.form.agree##] = true and '[##cms.form.pass]' = '[##cms.form.confirm-pass##]'

   For more Information See :doc:`expression`



.. _Complex-Conditional-Execution :

Complex Conditional Execution
-----------------------------

In this example we go to use complex :doc:`expression` for set :class:`if` attribute to present custom business in conditional rendering.

.. note:: 
   For simplicity, we remove unnecessary part of command in this example.

our simple print command that use in this example is:

.. code-block:: html
   :linenos:

   <basis core="print" datamembername="db.test-data" >
      <face>
         <h1>@title</h1>
      </face>
   </basis>

Suppose client request :class:`query string` contain :class:`A`, :class:`B` and :class:`C` key.
Value for this keys is :class:`2`, :class:`3` , :class:`6` respectively.
Now set :class:`[##cms.query.A##]*[##cms.query.b##] = [##cms.query.C##]` expression for :class:`if` attribute:


.. code-block:: html
   :linenos:

   <basis core="print" if="[##cms.query.A##]*[##cms.query.b##] = [##cms.query.C##]">
      [...]
   </basis>

In generating result process :class:`print` command execute because after replace process in :class:`if` attribute
, new expression is :class:`2*3 = 6` that is true value after evaluation.

More True Example::

   * [##cms.query.A##] = [##cms.query.C##]/[##cms.query.b##]
   * ([##cms.query.A##] = 2) and ([##cms.query.b##] = 3)
   * ([##cms.query.A##] = 2) OR ([##cms.query.b##] = 7)
   * ([##cms.query.A##] = 2) and ([##cms.query.b##] = 3 OR [##cms.query.b##] = 5)
   * not([##cms.query.A##] = 1)
   * NOT([##cms.query.b##] = 5 OR [##cms.query.c##] = 5)

More false Example::

   * [##cms.query.A##] = 6
   * ([##cms.query.A##] = 2) and ([##cms.query.b##] = 6)
   * ([##cms.query.A##] = 3) and ([##cms.query.b##] = 3 OR [##cms.query.c##] = 6)
   * not ([##cms.query.A##] = 2)


Related Topics
~~~~~~~~~~~~~~
* :doc:`expression`
* :doc:`builtin-commands`
* :doc:`renderable/renderable`
* :doc:`source/source`
* :doc:`collection/collection`
* :doc:`management/management`

.. toctree::
   :titlesonly:
   :hidden: