docs: Update docs to add new way to add conditions

Author: EnriqueSoria

docs/advanced.md

@@ -4,10 +4,10 @@
 
 These are available on your model instance when the mixin or extend the base model is used.
 
-| Method       | Details |
-|:-------------:|:-------------:|
-| `has_changed(field_name: str) -> bool` | Return a boolean indicating whether the field's value has changed since the model was initialized |
-| `initial_value(field_name: str) -> bool` | Return the value of the field when the model was first initialized |
+|                  Method                  |                                              Details                                              |
+|:----------------------------------------:|:-------------------------------------------------------------------------------------------------:|
+|  `has_changed(field_name: str) -> bool`  | Return a boolean indicating whether the field's value has changed since the model was initialized |
+| `initial_value(field_name: str) -> bool` |                Return the value of the field when the model was first initialized                 |
 
 ### Example
 You can use these methods for more advanced checks, for example:
@@ -29,6 +29,33 @@ class UserAccount(LifecycleModel):
 
 ```
 
+## Custom conditions <a id="custom-conditions"></a>
+Custom conditions can be created as long as they respect condition signature
+```python
+def changes_to_ned_flanders(instance, update_fields=None):
+    ...
+```
+
+To allow your custom conditions to be chainable, create a class based condition inheriting `ChainableCondition`.
+```python
+from django_lifecycle import BEFORE_SAVE
+from django_lifecycle.conditions import WhenFieldHasChanged
+from django_lifecycle.conditions.base import ChainableCondition
+
+
+class IsNedFlanders(ChainableCondition):
+    def __call__(self, instance, update_fields=None):
+        return instance.first_name == "Ned" and instance.last_name == "Flanders"
+
+    
+@hook(
+    BEFORE_SAVE,
+    condition=WhenFieldHasChanged("first_name") & WhenFieldHasChanged("last_name") & IsNedFlanders()
+)
+def foo():
+    ...
+```
+
 ## Suppressing Hooked Methods <a id="suppressing"></a>
 
 To prevent the hooked methods from being called, pass `skip_hooks=True` when calling save:

docs/hooks_and_conditions.md

@@ -7,19 +7,22 @@ set up conditions for when the method should fire.
 ## Decorator Signature
 
 ```python
-    @hook(
-        moment: str,
-        when: str = None,
-        when_any: List[str] = None,
-        has_changed: bool = None,
-        is_now: Any = '*',
-        is_not: Any = None,
-        was: Any = '*',
-        was_not: Any = None,
-        changes_to: Any = None,
-        priority: int = DEFAULT_PRIORITY,
-        on_commit: Optional[bool] = None
-    ):
+@hook(
+    moment: str,
+    condition: Optional[types.Condition] = None,
+    priority: int = DEFAULT_PRIORITY,
+    on_commit: Optional[bool] = None,
+    
+    # Legacy parameters
+    when: str = None,
+    when_any: List[str] = None,
+    has_changed: bool = None,
+    is_now: Any = '*',
+    is_not: Any = None,
+    was: Any = '*',
+    was_not: Any = None,
+    changes_to: Any = None,
+)
 ```
 
 ## Lifecycle Moments
@@ -40,7 +43,39 @@ Below is a full list of hooks, in the same order in which they will get called d
 All of hook constants are strings containing the specific hook name, for example `AFTER_UPDATE` is string
 `"after_update"` - preferably way is to use hook constant.
 
-## Condition Keyword Arguments
+## Conditions
+
+You can add a condition to specify in which case the hook will be fired or not, depending on the initial or current 
+state of a model instance's fields.
+
+There are some conditions already implemented, but you can provide your own condition, or even chain them using `&` and `|`.
+
+ - `WhenFieldChangesTo(field_name, has_changed)`
+ - `WhenFieldIsNow(field_name, is_now)`
+ - `WhenFieldIsNot(field_name, is_not)`
+ - `WhenFieldWas(field_name, was)`
+ - `WhenFieldWasNot(field_name, was_not)`
+ - `WhenFieldChangesTo(field_name, changes_to)`
+
+### Chaining conditions
+Conditions can be chained using `&` and `|` boolean operators
+
+```python
+from django_lifecycle.conditions import WhenFieldChangesTo
+from django_lifecycle import hook, BEFORE_UPDATE
+
+@hook(
+    BEFORE_UPDATE, 
+    condition=(
+        WhenFieldChangesTo("first_name", changes_to="Ned") 
+        & WhenFieldChangesTo("last_name", changes_to="Flanders")
+    )
+)
+def do_something(self):
+    ...
+```
+
+## Legacy Condition Keyword Arguments
 
 If you do not use any conditional parameters, the hook will fire every time the lifecycle moment occurs. You can use the keyword arguments below to conditionally fire the method depending on the initial or current state of a model instance's fields.