feature/#416 documentation for core notification

[toan-quach]

#416

[jrobinAV]

mkdocs.yml_template must be updated as well

[jrobinAV]

I just realize the Topic class is private. Instead of talking about topics we should talk about registration through the register method.

[jrobinAV]

I made a proposal to make a more direct index page

[FlorianJacta]

So, right now, there are no parts concerning the connection to the GUI?

[github-actions]

This PR has been labelled as "🥶Waiting for contributor" because it has been inactive for more than 14 days. If you would like to continue working on this PR, then please add new commit or another comment, otherwise this PR will be closed in 14 days. For more information please refer to the contributing guidelines.

[jrobinAV]

We need to add a couple of real examples.

[jrobinAV]

I just realize the Topic class is private. Instead of talking about topics we should talk about registration through the register method.

I made a proposal removing the term topic. @toan-quach please tell me what you think.

[FlorianJacta]

Revision of JR example on how to notify the user of a Core event:

import taipy as tp
from taipy import Config, Core, Gui, Scope
from taipy.gui import notify
import taipy.gui.builder as tgb
from taipy.core.notification import (
    Notifier,
    CoreEventConsumerBase,
    EventOperation,
    EventEntityType,
)
from taipy.core import SubmissionStatus


##### Configuration and Functions #####
from taipy import Config


def build_message(name: str):
    return f"Hello {name}!"


name_data_node_cfg = Config.configure_data_node(id="input_name", default_data="Florian")
message_data_node_cfg = Config.configure_data_node(id="message")
build_msg_task_cfg = Config.configure_task(
    "build_msg", build_message, name_data_node_cfg, message_data_node_cfg
)
scenario_cfg = Config.configure_scenario("scenario", task_configs=[build_msg_task_cfg])
#### Listen on Core Events ####


value = "Default text"


class SpecificCoreConsumer(CoreEventConsumerBase):
    def __init__(self, gui):
        self.gui = gui
        reg_id, queue = (
            Notifier.register()
        )  # Adapt the registration to the events you want to listen to
        super().__init__(reg_id, queue)

    def process_event(self, event):
        if event.operation == EventOperation.CREATION:
            if event.entity_type == EventEntityType.SCENARIO:
                self.gui.broadcast_callback(notify_users_of_creation)
        elif event.operation == EventOperation.UPDATE:
            if event.entity_type == EventEntityType.SUBMISSION:
                print(event)
                if event.attribute_value == SubmissionStatus.COMPLETED:
                    scenario_id = event.metadata["origin_entity_id"]
                    scenario = tp.get(scenario_id)
                    new_value_of_dn = scenario.message.read()
                    self.gui.broadcast_callback(
                        notify_users_of_update, [new_value_of_dn]
                    )
        else:
            pass


#### Notification function to be called ####


def notify_users_of_creation(state):
    state.value = "Scenario created and submitted"
    notify(state, "s", "Scenario Created")


def notify_users_of_update(state, new_value_of_dn):
    print("Value of Data Node:", new_value_of_dn)
    state.value = f"Data Node updated with value: {new_value_of_dn}"
    notify(state, "i", "Data Node Updated")


#### Normal callbacks ####


def create_and_submit_scenario(state):
    scenario = tp.create_scenario(config=scenario_cfg)
    tp.submit(scenario)


#### Page ####

with tgb.Page() as page:
    tgb.text("{value}")
    tgb.button("Press me!", on_action=create_and_submit_scenario)


if __name__ == "__main__":
    core = Core()
    gui = Gui(page)
    core.run()
    SpecificCoreConsumer(gui).start()
    gui.run()

[2024-08-22 17:52:03.010][Taipy][INFO] job JOB_build_msg_56045147-372b-4968-85b5-c0a70d38cf6e is completed.

Value of Data Node: Hello Florian

[jrobinAV]

I would add a short description and explanation of the example with some motivation.
It would also be great to add examples showing how to integrate with an external system, like sending an email when a job fails and calling a Rest API when a new cycle is created.