From 9d732500de91857fb42e587e24a4366c8139e593 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= <hi_kalkan@yahoo.com>
Date: Thu, 15 Oct 2020 17:29:41 +0300
Subject: [PATCH] Add event doc for js

---
 .../en/UI/AspNetCore/JavaScript-API/Events.md | 88 +++++++++++++++++++
 docs/en/UI/AspNetCore/JavaScript-API/Index.md |  2 +-
 docs/en/docs-nav.json                         |  4 +
 3 files changed, 93 insertions(+), 1 deletion(-)
 create mode 100644 docs/en/UI/AspNetCore/JavaScript-API/Events.md

diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Events.md b/docs/en/UI/AspNetCore/JavaScript-API/Events.md
new file mode 100644
index 0000000000..3425355f44
--- /dev/null
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Events.md
@@ -0,0 +1,88 @@
+# ASP.NET Core MVC / Razor Pages UI: JavaScript Events API
+
+`abp.event` object is a simple service that is used to publish and subscribe to global events **in the browser**.
+
+> This API is not related to server side local or distributed events. It works in the browser boundaries to make the UI components (code parts) communicate in a loosely coupled way.
+
+## Basic Usage
+
+### Publishing Events
+
+Use `abp.event.trigger` to publish events.
+
+**Example: Publish a *Basket Updated* event**
+
+````js
+abp.event.trigger('basketUpdated');
+````
+
+This will trigger all the subscribed callbacks.
+
+### Subscribing to the Events
+
+Use `abp.event.on` to subscribe to events.
+
+**Example: Consume the *Basket Updated* event**
+
+````js
+abp.event.on('basketUpdated', function() {
+  console.log('Handled the basketUpdated event...');
+});
+````
+
+You start to get events after you subscribe to the event.
+
+### Unsubscribing from the Events
+
+If you need to unsubscribe from a pre-subscribed event, you can use the `abp.event.off(eventName, callback)` function. In this case, you have the callback as a separate function declaration.
+
+**Example: Subscribe & Unsubscribe**
+
+````js
+function onBasketUpdated() {
+  console.log('Handled the basketUpdated event...');
+}
+
+//Subscribe
+abp.event.on('basketUpdated', onBasketUpdated);
+
+//Unsubscribe
+abp.event.off('basketUpdated', onBasketUpdated);
+````
+
+You don't get events after you unsubscribe from the event.
+
+## Event Arguments
+
+You can pass arguments (of any count) to the `trigger` method and get them in the subscription callback.
+
+**Example: Add the basket as the event argument**
+
+````js
+//Subscribe to the event
+abp.event.on('basketUpdated', function(basket) {
+  console.log('The new basket object: ');
+  console.log(basket);
+});
+
+//Trigger the event
+abp.event.trigger('basketUpdated', {
+  items: [
+    {
+      "productId": "123",
+      "count": 2
+    },
+    {
+      "productId": "832",
+      "count": 1
+    }
+  ]
+});
+````
+
+### Multiple Arguments
+
+If you want to pass multiple arguments, you can pass like `abp.event.on('basketUpdated', arg0, arg1, agr2)`. Then you can add the same argument list to the callback function on the subscriber side.
+
+> **Tip:** Alternatively, you can send a single object that has a separate field for each argument. This makes easier to extend/change the event arguments in the future without breaking the subscribers.
+
diff --git a/docs/en/UI/AspNetCore/JavaScript-API/Index.md b/docs/en/UI/AspNetCore/JavaScript-API/Index.md
index 9e960ba240..dc87739641 100644
--- a/docs/en/UI/AspNetCore/JavaScript-API/Index.md
+++ b/docs/en/UI/AspNetCore/JavaScript-API/Index.md
@@ -8,7 +8,7 @@ ABP provides a set of JavaScript APIs for ASP.NET Core MVC / Razor Pages applica
 * abp.auth
 * abp.currentUser
 * abp.dom
-* abp.event
+* [abp.event](Events.md)
 * abp.features
 * [abp.localization](Localization.md)
 * abp.log
diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json
index 5e3f23cbc3..c14349b4ac 100644
--- a/docs/en/docs-nav.json
+++ b/docs/en/docs-nav.json
@@ -470,6 +470,10 @@
                 {
                   "text": "Notify",
                   "path": "UI/AspNetCore/JavaScript-API/Notify.md"
+                },
+                {
+                  "text": "Events",
+                  "path": "UI/AspNetCore/JavaScript-API/Events.md"
                 }
               ]
             },