From 3133e10570fa070393978a12d2e5cd592fe1713a Mon Sep 17 00:00:00 2001
From: Thinh Nguyen <117440893+nhthinh-axonivy@users.noreply.github.com>
Date: Thu, 5 Dec 2024 10:12:15 +0700
Subject: [PATCH] Document/ivyportal 17805 update documentation for i frame
task template configuration (#1285)
* document/IVYPORTAL-17805-Update-documentation-for-IFrame-task-template-configuration
_ update document in code
_ update document
---
.../restricted/IFrameTaskTemplate.xhtml | 140 ++++++-----
.../portal-developer-guide/iframe/index.rst | 230 +++++++++++++-----
2 files changed, 252 insertions(+), 118 deletions(-)
diff --git a/AxonIvyPortal/portal/webContent/layouts/restricted/IFrameTaskTemplate.xhtml b/AxonIvyPortal/portal/webContent/layouts/restricted/IFrameTaskTemplate.xhtml
index eb85ed0512f..c9cda06739d 100644
--- a/AxonIvyPortal/portal/webContent/layouts/restricted/IFrameTaskTemplate.xhtml
+++ b/AxonIvyPortal/portal/webContent/layouts/restricted/IFrameTaskTemplate.xhtml
@@ -9,69 +9,87 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+ **Task Details:**
+ - taskName: (String) Custom text for the task name.
+ - taskIcon: (String) Icon for the task, using Streamline or Awesome font (e.g., `si si-arrow-right`).
+ - isHideTaskName: (Boolean) Hides the task name when true. Default is false.
+
+ **Case Information:**
+ - caseId: (String) ID of the case to be displayed in the case information dialog.
+ - isHideCaseInfo: (Boolean) Hides the `Show Information` button when true. Default is false.
+
+ **Process Steps:**
+ - currentProcessStep: (Number/String) Current step in the process, either as an index or step name.
+ - processSteps: (Array/String) List of process steps (e.g., `["Create Investment Request", "Approve Investment Request"]`)
+ or JSON (e.g., `#{portalComponentUtilsBean.convertToJSON(data.steps)}`).
+ - isShowAllSteps: (Boolean) Displays all steps on large screens when true. Default is false.
+ - processChainDirection: (String) Orientation of the process chain, either `VERTICAL` or `HORIZONTAL` (default).
+ - processChainShape: (String) Shape of the process chain, either `LINE` or `CIRCLE` (default).
+
+ **Task Actions:**
+ - isHideTaskAction: (Boolean) Hides the task action button when true. Default is false.
+ - isWorkingOnATask: (Boolean) Indicates if a task is currently being worked on, useful for displaying a warning when leaving the page. Default is true.
+
+ **Miscellaneous:**
+ - announcementInvisible: (Boolean) Makes the announcement invisible when true. Default is false.
+ - isCardFrame: (Boolean) Displays content of the IFrame inside a card-style container when true.
+ - viewName: (String) Defines a custom breadcrumb view. Possible values:
+ `HOME, PROCESS, TASK, TASK_DETAIL, CASE_DETAIL, CASE, TECHNICAL_CASE, RELATED_TASK, USER_PROFILE,
+ ABSENCES_MANAGEMENT, DASHBOARD_CONFIGURATION, EDIT_DASHBOARD_DETAILS, PROCESS_VIEWER, PORTAL_MANAGEMENT, NOTIFICATION`.
+
+ -->
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/portal-guide/source/portal-developer-guide/iframe/index.rst b/Documentation/portal-guide/source/portal-developer-guide/iframe/index.rst
index 6a4196590f6..8a03edbc6e0 100644
--- a/Documentation/portal-guide/source/portal-developer-guide/iframe/index.rst
+++ b/Documentation/portal-guide/source/portal-developer-guide/iframe/index.rst
@@ -11,7 +11,11 @@ your HTML dialog independent of the **Portal**. It is rendered automatically in
.. _iframe-usage:
-Templates to use with IFrame: frame-10 templates (Provided by core, uses Freya theme). This template fully supports responsiveness.
+Templates to Use with IFrame
+============================
+
+Use the ``frame-10`` templates (provided by the core and using the Freya theme).
+These templates fully support responsive designs.
How To Use
==========
@@ -21,54 +25,90 @@ How To Use
Follow these steps to use the IFrame approach:
-#. Your HTML User Dialog has to be independent of the **Portal**. You can use
- the ``frame-_x_`` template in designer, or your own template. **Portal** will
- render it automatically in an IFrame.
-
-#. If you don't want to use the default configuration, apply one of the following three
- levels to open your task(s) in an IFrame:
-
- - Task level: in Task custom fields, set the ``embedInFrame`` field to
-
- - ``true``: start inside IFrame
- - ``false``: not start inside IFrame
- - Don't set if you want to use case or engine level
-
- |task-embedInFrame|
-
- - Case level: in Case custom fields, set the ``embedInFrame`` String field to
-
- - ``true``: start inside IFrame
- - ``false``: not start inside IFrame
- - Don't set if you want to use engine level
-
- |case-embedInFrame|
-
- - Engine level:
-
- - The **Portal Administrator** can define globally that all of the tasks
- running on the engine are started inside IFrames by using the
- ``Portal.EmbedInFrame`` Portal setting. refer to
- :ref:`update-portal-settings`
+#. **HTML Dialog Independence**
+
+ Ensure your HTML User Dialog is independent of the **Portal**. You can use the ``frame-_x_``
+ template in the designer or your own custom template. **Portal** will automatically render it in an IFrame.
+
+#. **Configuration Levels**
+ If you want custom behavior, configure at one of the following levels to open your tasks in an IFrame:
+
+ - **Task Level**: Set the ``embedInFrame`` field in Task custom fields to:
+
+ - ``true``: Start inside IFrame.
+ - ``false``: Do not start inside IFrame.
+ - Leave unset to use case or engine-level configuration.
+
+ |task-embedInFrame|
+
+ - **Case Level**: Set the ``embedInFrame`` String field in Case custom fields to:
+
+ - ``true``: Start inside IFrame.
+ - ``false``: Do not start inside IFrame.
+ - Leave unset to use engine-level configuration.
+
+ |case-embedInFrame|
+
+ - **Engine Level**:
+
+ The **Portal Administrator** can globally configure all tasks to start inside IFrames by setting the ``Portal.EmbedInFrame`` value in the Portal settings.
+ Refer to :ref:`update-portal-settings`.
.. _iframe-configure-template:
-Configure template
+Configure Template
==================
-**Portal** supports some configurations for templates like:
+The **Portal** allows configuration of templates with the following options:
-#. Name and icon of the working task.
+#. Name and icon for the working task.
+#. Process chain configuration.
+ (See: :ref:`components-portal-components-process-chain`).
+#. Show/hide case details and other actions.
-#. Configuration of :ref:`components-portal-components-process-chain`.
-#. Show/hide case details and other actions.
+Template Parameters
+-------------------
+
+The following parameters are available for this template:
+
+**Task Details**
+
+- ``taskName``: Custom text for the task name.
+- ``taskIcon``: Icon for the task, using Streamline or Awesome font.
+- ``isHideTaskName``: Hides the task name when true.
+
+**Case Information**
+
+- ``caseId``: ID of the case to be displayed in the case information dialog.
+- ``isHideCaseInfo``: Hides the ``Show Information`` button when true.
+
+**Process Steps**
-|task-name-template|
+- ``currentProcessStep``: Current step in the process, either as an index or step name.
+- ``processSteps``: List of process steps or JSON.
+- ``isShowAllSteps``: Displays all steps on large screens when true.
+- ``processChainDirection``: Orientation of the process chain, either ``VERTICAL`` or ``HORIZONTAL``.
+- ``processChainShape``: Shape of the process chain, either ``LINE`` or ``CIRCLE``.
-You could configure UI in either of these two ways:
+**Task Actions**
-#. Using the component IFrameTaskConfig (recommended)
+- ``isHideTaskAction``: Hides the task action button when true.
+- ``isWorkingOnATask``: Indicates if a task is currently being worked on,
+ useful for displaying a warning when leaving the page.
+
+**Miscellaneous**
+
+- ``announcementInvisible``: Makes the announcement invisible.
+- ``isCardFrame``: Displays content of the IFrame inside a card-style container.
+- ``viewName``: Defines a custom breadcrumb view.
+
+Configuration Methods
+---------------------
+
+You can configure the UI in one of two ways:
+
+#. **Using ``IFrameTaskConfig`` Component** (Recommended)
.. code-block:: xml
@@ -96,13 +136,13 @@ You could configure UI in either of these two ways:
-#. Using Javascript
+#. **Using JavaScript**
.. code-block:: xml
- ...
+ ...
...
-Configure Task name
--------------------
+Configure Task Details
+----------------------
+You can customize task details, such as the task name and icon.
-By default, **Portal** uses the name of the working task.
+**Parameters:**
+ - ``taskName``: Custom text for the task name.
+ - ``taskIcon``: Using Streamline or Awesome font (e.g., `si si-arrow-right`).
+ - ``isHideTaskName``: Set to ``true`` to hide the task name. Default is ``false``.
-Options for ``Task name``
+**Example:**
-.. csv-table::
- :file: documents/available_task_options.csv
- :widths: 20 50
- :header-rows: 1
- :class: longtable
+.. code-block:: xml
-Example using IFrameTaskConfig:
+
+
+ ...
+
+ ...
+
+
+
+
+Configure Case Information
+--------------------------
+Customize how case details are displayed and whether to show the "Show Information" button.
+
+**Parameters:**
+ - ``caseId``: The ID of the case to display in the information dialog.
+ - ``isHideCaseInfo``: Set to ``true`` to hide the "Show Information" button.
+ Default is ``false``.
+
+**Example:**
.. code-block:: xml
...
-
+ ...
+
+
+
+Configure Task Actions
+----------------------
+Control the visibility and behavior of task-related buttons and actions.
+
+**Parameters:**
+ - ``isHideTaskAction``: Set to ``true`` to hide the task action button.
+ Default is ``false``.
+ - ``isWorkingOnATask``: Indicates if the task is active.
+ Useful for displaying a warning when leaving the page. Default is ``true``.
+
+**Example:**
+
+.. code-block:: xml
+
+
+
+ ...
+
+ ...
+
+
+
+
+Configure Miscellaneous Options
+-------------------------------
+Additional settings can influence the layout and visibility of elements.
+
+**Parameters:**
+ - ``announcementInvisible``: Set to ``true`` to hide announcements.
+ Default is ``false``.
+ - ``isCardFrame``: Set to ``true`` to display the IFrame
+ content inside a card-style container.
+ - ``viewName``: Custom breadcrumb view. Possible values are:
+ ``HOME, PROCESS, TASK, TASK_DETAIL, CASE_DETAIL, CASE, TECHNICAL_CASE, RELATED_TASK,
+ USER_PROFILE, ABSENCES_MANAGEMENT, DASHBOARD_CONFIGURATION, EDIT_DASHBOARD_DETAILS,
+ PROCESS_VIEWER, PORTAL_MANAGEMENT, NOTIFICATION``.
+
+**Example:**
+
+.. code-block:: xml
+
+
+
+ ...
+
...