===============================
EOQ Action Integration
===============================

EOQ Actions allow executing python scripts that interact with the EOQ domain.

###################
Actions Directory
###################

Make sure that you start your XGEE application with "actions" and an action directory 
by configuring it in
the `config.yaml` file.

.. code-block:: yaml

  app:
  name: OAAM Toolbox
  port: 8080
  eoq:
    port: 8000
    workspace: ./workspace
    actions: ./actions
    meta: ./meta

This will start the EOQ domain with the actions directory.


#############################
Activate eoq.actions plugin
#############################

Activate the eoq.actions plugin in your config, e.g. like this

.. code-block:: javascript

   {
     "eoq.actions": {
       "enabled": true,
       "config": {
         "menuId": "ACTIONS_MENU",
         "menuName": "Actions",
         "appendBefore": true,
         "appendMenuId": "HELP_MENU"
       }
     }
   }


Now, XGEE will add a menu entry "Actions" to the menu bar. 


#############################
Filtering Actions
#############################

By default, it will add all actions to the menu and provide a graphical interface
to select the action and set its arguments. 

However, you can provide `actionFilterFunction` to filter the actions that are shown in the menu:

.. code-block:: javascript

  actionFilterFunction: (action) =>
      !action.tags.includes("advanced") || window.location.search.includes("advanced"),

This will only show actions that are tagged with "advanced" if the URL contains the query parameter "advanced". 
E.g. `?advanced` will show advanced actions, while no query parameter will only show normal actions.



#############################
Debugging Actions
#############################

During debugging, you might want to check why actions are not shown. Use the EOQ2 Developer interface
to list all actions on: http://xgee.de:9001/

Get all actions with: ```GAA```. Without filters, all actions shown here will be shown in the XGEE Actions menu. 
Test an action with ```CAL 'helloworld'```

Find further information about the unfortunately not fully documented EOQ2 Actions in the EOQ2 documentation: 
https://gitlab.com/eoq/doc/-/raw/master/EoqUserManual.pdf

######################
Overview EOQ2 Actions
######################
Don't use ```__init__.py``` files in the actions directory

Every python module (file) in the actions directory and subdirectories is an action if it contains a function 
with the same name as the module. E.g. ```helloworld.py``` contains a function ```helloworld()```

The first argument of an action is always ```domain```.

EOQ uses an unusual way of argument descriptions that is not fully compatible with python typing. 
The descriptions will be shown in the XGEE Actions menu. Here is an example of an EOQ2 action:

.. code-block:: python

  '''
    Automatic signal routing using Dijkstra
  '''

  from oaamUtils import autorouter

  def autoroute(domain : 'Domain',         
          hardware : 'Hardware: The OAAM hardware element.',
          functions : 'Functions: The OAAM functions element.',
          allocation: 'Allocations: The OAAM allocations element.'  
          ) -> "Bool:Whether the generation succeeded or not.":

      res=autorouter.run(domain,hardware,functions,allocation)
      print(res)   
      pass