hooks diagrams

Author: ivictbor

adminforth/documentation/docs/tutorial/03-Customization/04-hooks.md

@@ -9,8 +9,43 @@ Hooks are used to:
 - modify the fetched data before it is displayed in the list and show
 - prevent the request to db depending on some condition (Better use [allowedActions](./05-limitingAccess.md) for this)
 
+Every hook is executed when AdminForth frontend makes some internal API HTTP request to the backend.
 
-## Modify the data before it is saved to the database
+Every hook must return one of two objects:
+1) If everything is fine and request flow should be continued hook should return `{ ok: true }`
+2) If for some reason you need to interrupt request flow in hook you should return `{ ok: false, error: 'some error message for user' }`. This is
+handy for access-related tasks, though most of such tasks should be solved with [allowedActions](./05-limitingAccess.md) and not hooks.
+
+Every hook is array of async functions, so you can have multiple hooks for one event. 
+For simplicity of course you can specify hook as scalar async function and not as array, but internally it will be anyway converted to array with single element just after app start. Plugins can push new own hooks in front of yours (using `unshift`) or after yours (using `push`). For example audit log plugin adds hooks for registration of all changes in the database.
+
+Here we will consider possible flows one by one
+
+## Initial data for edit page flow
+
+When user opens edit page, AdminForth makes a request to the backend to get the initial data for the form.
+
+![Initial data for edit page flow](image-28.png)
+
+Practically you can use this hook to modify or add some data before it is displayed on the edit page. 
+
+For example [upload plugin](/docs/tutorial/Plugins/upload/) uses this hook to generate signed preview URL so user can see existing uploaded file preview  in form, and at the same time database stores only original file path which might be not accessible without presigned URL.
+
+## Saving data on edit page
+
+When user clicks the save button, AdminForth makes a request to the backend to save the data.
+
+![Saving data on edit page](image-27.png)
+
+Practically you can use this hook to modify the data or populate new fields before it is saved to the database.
+
+## Saving data on create page
+
+When user clicks the save button from create page, AdminForth makes a request to the backend to save the data.
+
+![Saving data on create page](image-26.png)
+
+### Example: modify the created object before it is saved to the database
 
 Let's add reference to `adminUser` when user creates a new apartment:
 
@@ -38,9 +73,9 @@ import type { AdminUser } from  'adminforth';
 //diff-add
     create: {
 //diff-add
-      beforeSave: async ({ adminUser, record }: { adminUser: AdminUser, record: any }) => {
+      beforeSave: async ({ adminUser, record }: { adminUser: AdminUser, updates: any }) => {
 //diff-add
-        record.realtor_id = adminUser.dbUser.id;
+        updates.realtor_id = adminUser.dbUser.id;
 //diff-add
         return { ok: true, record };
 //diff-add
@@ -52,11 +87,15 @@ import type { AdminUser } from  'adminforth';
 }
 ```
 
+In this way user who creates the apartment will be assigned as a realtor. 
 
-## Limiting access to user-related data
+## List page flow
 
+When user opens the list page, AdminForth makes a request to the backend to get the list of items.
 
-### List of entities
+![List page flow](image-22.png)
+
+### Example: limit access in list to user-related records
 
 For example we can prevent the user to see Apartments created by other users. Superadmin user still can see all:
 
@@ -90,13 +129,17 @@ For example we can prevent the user to see Apartments created by other users. Su
 }
 ```
 
-This hook will prevent the user to see Apartments created by other users in list, however user if will be able to discover
-the apartment id, will be able to use show page to see the apartment details. Let's limit it as well:
+This hook will prevent the user to see Apartments created by other users in list, however if user will be able to discover
+the apartment id, he will be able to use show page to see the apartment details, that is why separate limiting for show page is required as well. Below we will discover how to limit access to show page.
 
 ### Dropdown list of foreignResource
 
 By default if there is `foreignResource` like we use for demo on `realtor_id` column, the filter will suggest a
-select dropdown with list of all Realtors. This might be a leak to get id's of other users. Let's limit it:
+select dropdown with list of all Realtors. 
+
+This might bring us a leak where explorer will get id's of other users in the system which might be not desired 
+
+Let's limit it:
 
 ```ts title='./resources/apartments.ts'
 {
@@ -118,7 +161,22 @@ select dropdown with list of all Realtors. This might be a leak to get id's of o
 
 In our case we limit the dropdown list to show only the current user, however you can use same sample to list only objects who are related to the current user in case if you will have relation configurations which require to show related objects which belongs to the current user.
 
-### Show entity
+Flow diagram for dropdown list:
+
+![Flow diagram for dropdown list](image-30.png)
+
+## Show page flow
+
+When user opens the show page, AdminForth makes a request to the backend to get the item. This request ia absolutely the same as one for edit initial data, because naturally for most of cases data for show page are the same as initial data for edit page.
+
+However if you still need to distinguish between these two cases you can use `query.source` parameter in hook (we do not mentioned it in diagram for simplicity and rare demand).
+
+Here is show request flow:
+
+![Here is show request](image-29.png)
+
+
+### Example show limiting:
 
 ```ts title='./resources/apartments.ts'
 {
@@ -143,14 +201,14 @@ In our case we limit the dropdown list to show only the current user, however yo
 }
 ```
 
-> 👆 Please note that we use `response[0].realtor_id.pk` because this fiel has `foreignResource` in column option is set
+> 👆 Please note that we use `response[0].realtor_id.pk` because this field has `foreignResource` in column option is set
 > Otherwise you would use  just `response[0].realtor_id`
 
-Important notice: when using hook to filter out list of items for list page or list of items on dropdown makes a lot of sense (because gives ability to change filter of database request), using hook for show page is not reasonable:
+Important notice: Using hook to filter out list of items for list page or list of items for dropdown makes a lot of sense because gives ability to change filter of database request. However using hook for show page is not reasonable:
 
-First of all it sematicaly better aligns with using allowedActions interface. For this particular case you must use [allowedActions.show](./05-limitingAccess.md#disable-showing-the-resource-based-on-owner)
+First of all it semantically better aligns with using `allowedActions` interface. For this particular case you must use [allowedActions.show](./05-limitingAccess.md#disable-showing-the-resource-based-on-owner)
 
-Secondly limiting access from this hook will not prevent executing other hooks (e.g. beforeDatasourceRequest), when allowedActions check
+Secondly limiting access from this hook will not prevent executing other hooks (e.g. `beforeDatasourceRequest`), when allowedActions check
 always performed before any hooks and any database requests. 
 
 ## All hooks

adminforth/documentation/docs/tutorial/03-Customization/05-limitingAccess.md

@@ -1,6 +1,13 @@
 
 # Limiting actions access
 
+As you might have noticed in diagrams from [adminforth hooks](./04-hooks.md) section of this tutorial, AdminForth checks `options.allowedActions` before executing any action. In this section we will show real-code examples of how to limit access to actions based on user role or record values.
+
+Before we start it is worth to mention that callbacks or scalars defined in `allowedActions` are called/parsed not only before actual request but also before displaying buttons in the UI. So first time, when frontend loads any page of resource, it "calls" `allowedActions` to understand whether user has access to each function, and e.g. if it says that user can't delete record, AdminForth will not show delete icon in the UI:
+
+![Resource any page request](image-21.png)
+
+As you can see allowedAction callbacks are called in parallel in async manner. However it is important to keep them fast and not to make any slow operations in them, to keep UI responsive.
 
 ## Statically disable some action