Skip to content

Commit

Permalink
[#170] Support statically defined hooks
Browse files Browse the repository at this point in the history
  • Loading branch information
@javrasya
javrasya committed Aug 27, 2020
1 parent d26645d commit ff0d4a9
Show file tree
Hide file tree
Showing 28 changed files with 1,266 additions and 81 deletions.
84 changes: 84 additions & 0 deletions docs/admin/dynamichooks.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
.. _transition-meta-administration:

Dynamic Hook Administration
===========================

OnTransitHook
-------------
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| Field | Default | Optional | Format | Description |
+===========================+============+==========+====================+===========================================+
| workflow | | | Workflow | | Your model class along with the field |
| | | | | | that you want to use this transition |
| | | False | | | approval meta for. ``django-river`` |
| | | | | | will list all the possible model and |
| | | | | | fields you can pick on the admin page |
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| callback_function | | False | Function | | Call back function model object that |
| | | | | | contains the name and the body |
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| transition_meta | | False | TransitionMeta | | The meta of the transition that the |
| | | | | | callback function will be executed |
| | | | | | for |
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| hook_type | | False | BEFORE or AFTER | | When the call back should be executed |
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| workflow_object | None | True | ModelWithStateField| | Your model object. This field is |
| | | | | | When it is provided, the call back for |
| | | | | | the transition will only be executed for|
| | | | | | the given model object |
+---------------------------+------------+----------+--------------------+-------------------------------------------+


OnApprovedHook
--------------
+---------------------------+------------+----------+--------------------+--------------------------------------------------+
| Field | Default | Optional | Format | Description |
+===========================+============+==========+====================+==================================================+
| workflow | | | Workflow | | Your model class along with the field |
| | | | | | that you want to use this transition |
| | | False | | | approval meta for. ``django-river`` |
| | | | | | will list all the possible model and |
| | | | | | fields you can pick on the admin page |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
| callback_function | | False | Function | | Call back function model object that |
| | | | | | contains the name and the body |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
| transition_approval_meta | | False | TransitionApprovalMeta | | The meta of the approval that the |
| | | | | | callback function will be executed |
| | | | | | for |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
| hook_type | | False | BEFORE or AFTER | | When the call back should be executed |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
| workflow_object | None | True | ModelWithStateField | | Your model object. This field is |
| | | | | | When it is provided, the call back for |
| | | | | | the transition will only be executed for|
| | | | | | the given model object |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+


OnCompleteHook
--------------
+---------------------------+------------+----------+--------------------+--------------------------------------------------+
| Field | Default | Optional | Format | Description |
+===========================+============+==========+====================+==================================================+
| workflow | | | Workflow | | Your model class along with the field |
| | | | | | that you want to use this transition |
| | | False | | | approval meta for. ``django-river`` |
| | | | | | will list all the possible model and |
| | | | | | fields you can pick on the admin page |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
| callback_function | | False | Function | | Call back function model object that |
| | | | | | contains the name and the body |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
| hook_type | | False | BEFORE or AFTER | | When the call back should be executed |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+
| workflow_object | None | True | ModelWithStateField | | Your model object. This field is |
| | | | | | When it is provided, the call back for |
| | | | | | the transition will only be executed for|
| | | | | | the given model object |
+---------------------------+------------+----------+---------------------------+-------------------------------------------+

.. toctree::
:maxdepth: 2
30 changes: 30 additions & 0 deletions docs/admin/function.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
.. _transition-meta-administration:

Function Administration
=======================

With dynamically created hookins, functions are kept in DB and they can be managed on an admin interface that django-river already offers out of the box.
You define them once and you can use them within multiple hooks. Just go to ``/admin/river/function/`` admin page and create your functions there.
The admin page also comes with code highlighting if you enable the ``codemirror2`` in the settings. Don't forget to collect statics for production deployments.


.. code:: python
INSTALLED_APPS=[
...
codemirror2
river
...
]
+-------+---------+----------+----------------------------+-------------+------------------------------+
| Field | Default | Optional | Format | Description | |
+=======+=========+==========+============================+=============+==============================+
| name | | False | String ([\w\s]+) | | Name of the function. |
+-------+---------+----------+----------------------------+-------------+------------------------------+
| body | | False | Valid Python function that | | Function body as string. |
| | | | is named as ``handle`` | | see :ref:`Example Function` |
+-------+---------+----------+----------------------------+-------------+------------------------------+

.. toctree::
:maxdepth: 2
3 changes: 2 additions & 1 deletion docs/admin/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,5 @@ is to provide them by using their Django admin pages.
state
transition_meta
transition_approval_meta

dynamichooks
function
14 changes: 7 additions & 7 deletions docs/admin/state.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
State Administration
====================

+-------------+--------------+----------+--------------+-----------------------------+
| Field | Default | Optional | Format | Description |
+=============+==============+==========+==============+=============================+
| label | NaN | False | String (\w+) | A name for the state |
+-------------+--------------+----------+--------------+-----------------------------+
| description | Empty string | True | String (\w+) | A description for the state |
+-------------+--------------+----------+--------------+-----------------------------+
+-------------+--------------+----------+------------------+-----------------------------+
| Field | Default | Optional | Format | Description |
+=============+==============+==========+==================+=============================+
| label | NaN | False | String ([\w\s]+) | A name for the state |
+-------------+--------------+----------+------------------+-----------------------------+
| description | Empty string | True | String ([\w\s]+) | A description for the state |
+-------------+--------------+----------+------------------+-----------------------------+

.. toctree::
:maxdepth: 2
Expand Down
8 changes: 4 additions & 4 deletions docs/admin/transition_approval_meta.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@ Transition Approval Meta Administration
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| Field | Default | Optional | Format | Description |
+===========================+============+==========+====================+===========================================+
| workflow | | | | Choice | | Your model class along with the field |
| | | | | of | | that you want to use this transition |
| | | False | | Strings | | approval meta for. ``django-river`` |
| workflow | | | Workflow | | Your model class along with the field |
| | | | | | that you want to use this transition |
| | | False | | | approval meta for. ``django-river`` |
| | | | | | will list all the possible model and |
| | | | | | fields you can pick on the admin page |
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| transition_meta | | False | TransitionMete | | Transition information that contains |
| transition_meta | | False | TransitionMeta | | Transition information that contains |
| | | | | | source and destination states |
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| permissions | Empty List | True | List<Permission> | | List of permissions which will be |
Expand Down
6 changes: 3 additions & 3 deletions docs/admin/transition_meta.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ Transition Meta Administration
+---------------------------+------------+----------+--------------------+-------------------------------------------+
| Field | Default | Optional | Format | Description |
+===========================+============+==========+====================+===========================================+
| workflow | | False | | Choice | | Your model class along with the field |
| | | | | of | | that you want to use this transition |
| | | False | | Strings | | approval meta for. ``django-river`` |
| workflow | | False | Workflow | | Your model class along with the field |
| | | | | | that you want to use this transition |
| | | | | | approval meta for. ``django-river`` |
| | | | | | will list all the possible model and |
| | | | | | fields you can pick on the admin page |
+---------------------------+------------+----------+--------------------+-------------------------------------------+
Expand Down
60 changes: 60 additions & 0 deletions docs/api/class.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,5 +54,65 @@ True
| Output | List<State> | List of the final states in the workflow |
+--------+-------------+------------------------------------------+

Class Level Hooking API
=======================

Please see ':ref:`Implement a Function`' to know how to implement a callback function.

on_pre_approve
--------------

To register a hook for all the objects with a statically defined callback function that will
be executed right before an approve happens.

>>> MyModel.river.my_state_field.on_pre_approve(callback_function, transition_approval_meta)
None

on_post_approve
---------------

To register a hook for all the objects with a statically defined callback function that will
be executed right after an approve happens.

>>> MyModel.river.my_state_field.on_post_approve(callback_function, transition_approval_meta)
None

on_pre_transition
-----------------

To register a hook for all the objects with a statically defined callback function that will
be executed right before a transition happens.

>>> MyModel.river.my_state_field.on_pre_transition(callback_function, transition_approval_meta)
None

on_post_transition
------------------

To register a hook for all the objects with a statically defined callback function that will
be executed right after a transition happens.

>>> MyModel.river.my_state_field.on_post_transition(callback_function, transition_meta)
None


on_pre_complete
-----------------

To register a hook for all the objects with a statically defined callback function that will
be executed right before a the whole flow is complete.

>>> MyModel.river.my_state_field.on_pre_complete(callback_function)
None

on_post_complete
------------------

To register a hook for all the objects with a statically defined callback function that will
be executed right after a the whole flow is complete.

>>> MyModel.river.my_state_field.on_post_complete(callback_function)
None

.. toctree::
:maxdepth: 2
60 changes: 60 additions & 0 deletions docs/api/instance.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -158,5 +158,65 @@ purposes.
| | | | | of the workflow object |
+-------------------+--------+--------------------------+------------------------------------------+

Instance Level Hooking API
==========================

Please see ':ref:`Implement a Function`' to know how to implement a callback function.

on_pre_approve
--------------

To register a hook for either a specific object with a statically defined callback function that will
be executed right before an approve happens.

>>> my_model.river.my_state_field.on_pre_approve(callback_function, transition_approval_meta)
None

on_post_approve
---------------

To register a hook for either a specific object with a statically defined callback function that will
be executed right after an approve happens.

>>> my_model.river.my_state_field.on_post_approve(callback_function, transition_approval_meta)
None

on_pre_transition
-----------------

To register a hook for either a specific object with a statically defined callback function that will
be executed right before a transition happens.

>>> my_model.river.my_state_field.on_pre_transition(callback_function, transition_approval_meta)
None

on_post_transition
------------------

To register a hook for either a specific object with a statically defined callback function that will
be executed right after a transition happens.

>>> my_model.river.my_state_field.on_post_transition(callback_function, transition_meta)
None


on_pre_complete
-----------------

To register a hook for either a specific object with a statically defined callback function that will
be executed right before a the whole flow is complete.

>>> my_model.river.my_state_field.on_pre_complete(callback_function)
None

on_post_complete
------------------

To register a hook for either a specific object with a statically defined callback function that will
be executed right after a the whole flow is complete.

>>> my_model.river.my_state_field.on_post_complete(callback_function)
None

.. toctree::
:maxdepth: 2
9 changes: 8 additions & 1 deletion docs/changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,13 @@
Change Logs
===========

3.3.0:
------
* **Improvement** - # 170_ : Support hooks with statically defined callback functions that are in the workspace


.. _170: https://github.com/javrasya/django-river/issues/170

3.2.0 (Stable):
---------------
* **Improvement** - # 140_ 141_: Support Microsoft SQL Server 17 and 19
Expand All @@ -29,7 +36,7 @@ Change Logs
3.1.2:
------
* **Improvement** - # 133_: Support MySQL 8.0

_handle_my_transitions

.. _133: https://github.com/javrasya/django-river/issues/133

Expand Down
1 change: 1 addition & 0 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosectionlabel',
]

# Add any paths that contain templates here, relative to this directory.
Expand Down
Loading

0 comments on commit ff0d4a9

Please sign in to comment.