notes on guest os category changes and modern image selection (apache#519)

Related #10773

Signed-off-by: Abhishek Kumar <[email protected]>

Author: shwstppr

source/_static/images/add-guest-os-category.png

@@ -13,6 +13,13 @@
    specific language governing permissions and limitations
    under the License.
 
+
+.. |guest-os-categories.png| image:: /_static/images/guest-os-categories.png
+   :alt: Guest OS Categories
+
+.. |add-guest-os-category.png| image:: /_static/images/add-guest-os-category.png
+   :alt: Add Guest OS Category form
+
 .. |guest-os-button.png| image:: /_static/images/guest-os-button.png
    :alt: Guest OS section
 
@@ -36,8 +43,40 @@ and also need to have a mapping with the actual operating system name supported
 
 Under "Configuration" section there are sub-sections for guest operating system.
 
+Guest OS Categories
+-------------------
+
+A list of existing categories for the guest operating systems are shown as
+"Guest OS Categories" section. Operators can also add new guest operating
+system categories from the view.
+
+|guest-os-categories.png|
+
+Guest operating system categories are useful for categorizing images, i.e.,
+templates and ISOs, in several UI forms such as deploying an instance,
+reinstalling an instance, etc., when the modern image selection is used in the
+UI configuration.
+
+To allow a guest operating system category to be displayed in the UI forms, it
+must be marked as featured. The order of the categories can also be controlled
+using the Order option in the categories view.
+
+Like other resources, a custom resource icon can be set for a particular guest
+operating system category for further control. If no resource icon is set for
+a category, the UI will display default icons based on the category
+name.
+
+An existing guest OS category can be deleted if it does not have any
+associated guest operating systems.
+
+The "Add guest OS category" option allows operators to create new categories,
+which can be marked as featured if they are meant to be displayed in the UI
+forms.
+
+|add-guest-os-category.png|
+
 Guest OS
----------
+--------
 
 A list of supported guest operating systems are shown under |guest-os-button.png| and also one can add new operating systems.
 
@@ -86,4 +125,4 @@ and following details needs to be provided.
    :align: center
    :alt: Guest OS mapping form
 
-Operator can also do operations like edit and delete guest OS and its hypervisor mappings.
+Operator can also do operations like edit and delete guest OS and its hypervisor mappings.

source/_static/images/guest-os-categories.png

@@ -178,30 +178,33 @@ new, unique value.
 
 #. Type the new password, and click OK.
 
-Basic UI Customization
+Basic UI Customisation
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Users can customize the CloudStack's user interface by means of a configuration file at /etc/cloudstack/management/config.json which can be used to modify the theme, logos, etc. to align to one's requirement.
 
 To change the logo, login banner, error page icon, etc. the following details can be edited in config.json:
 
-============================= ================================================================
+======================================= ==================================================================================================================================================================
 Property                      Description
-============================= ================================================================
-apiBase                       Changes the suffix for the API endpoint
-docBase                       Changes the base URL for the documentation
-appTitle                      Changes the title of the portal
-footer                        Changes the footer text
-loginFavicon                  Changes the favicon of the login page
-loginFooter                   Configure to display text (HTML) in the footer at the login screen
-loginTitle                    Changes the title of the login page
-logo                          Changes the logo top-left side image
-minilogo                      Changes the logo top-left side image when menu is collapsed
-banner                        Changes the login banner image
-error.404                     Changes the image of error Page not found
-error.403                     Changes the image of error Forbidden
-error.500                     Changes the image of error Internal Server Error
-============================= ================================================================
+======================================= ==================================================================================================================================================================
+apiBase                                 Changes the suffix for the API endpoint
+docBase                                 Changes the base URL for the documentation
+appTitle                                Changes the title of the portal
+footer                                  Changes the footer text
+loginFavicon                            Changes the favicon of the login page
+loginFooter                             Configure to display text (HTML) in the footer at the login screen
+loginTitle                              Changes the title of the login page
+logo                                    Changes the logo top-left side image
+minilogo                                Changes the logo top-left side image when menu is collapsed
+banner                                  Changes the login banner image
+error.404                               Changes the image of error Page not found
+error.403                               Changes the image of error Forbidden
+error.500                               Changes the image of error Internal Server Error
+imageSelectionInterface                 Allows specifying view for image(template/ISO) selection in several UI forms. Supported values are: "modern" and "legacy". Default view is "modern"
+showUserCategoryForModernImageSelection Enables showing or hiding _User_ category in the *modern* image selection view which will show all user-owned images for the logged in user. Default value is true
+showAllCategoryForModernImageSelection  Enables showing or hiding _All_ category in the *modern* image selection view which will show all available images for the logged in user. Default value is false
+======================================= ==================================================================================================================================================================
 
 .. parsed-literal::
 
@@ -219,7 +222,7 @@ error.500                     Changes the image of error Internal Server Error
     }
 
 
-Customization of themes is also possible, such as, modifying banner width, general color, etc. This can be done by editing the "theme" section of the config.json file. Theme section provides following properties for customization:
+Customisation of themes is also possible, such as, modifying banner width, general color, etc. This can be done by editing the "theme" section of the config.json file. Theme section provides following properties for customisation:
 
 ============================= ================================================================
 Property                      Description
@@ -504,6 +507,22 @@ For displaying a custom HTML in the plugin, HTML file can be stored in the Cloud
 
 |ui-custom-plugin.png|
 
+
+Instance Image Selction Customisation
+-------------------------------------
+
+In the UI, there are several forms where the user needs to select an image (template/ISO) for an instance, such as deploying an instance, reinstalling an instance, creating a VNF appliance, etc. The image selection interface for these forms can be selected by the operator based on preference by specifying properties in the UI configuration file (config.json).
+
+The configuration property _imageSelectionInterface_ can be set to one of these values: modern or legacy. The default value is *modern*.
+
+When the *modern* interface is used, images will be categorized based on the guest operating system categories. Further customisation can be done using the configuration properties showUserCategoryForModernImageSelection and showAllCategoryForModernImageSelection to allow or disallow the display of additional categories.
+
+|ui-modern-image-selection.png|
+
+The *legacy* interface will display images based on templatefilter/isofilter, i.e., Featured, Community, My Templates/ISOs, and Shared.
+
+|ui-legacy-image-selection.png|
+
 Advanced UI Customisation
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -596,6 +615,12 @@ The following features are no longer supported or available in the UI but are st
 .. |change-password.png| image:: /_static/images/change-password.png
    :alt: button to change a User's password
 
+.. |ui-modern-image-selection.png| image:: /_static/images/ui-modern-image-selection.png
+   :alt: Modern Image Selection
+
+.. |ui-legacy-image-selection.png| image:: /_static/images/ui-legacy-image-selection.png
+   :alt: Legacy Image Selection
+
 .. |ui-custom-plugin.png| image:: /_static/images/ui-custom-plugin.png
    :alt: Custom plugin shown in UI with navigation
 

source/_static/images/ui-legacy-image-selection.png

@@ -76,3 +76,12 @@ On upgrading from 4.19.x or lower, existing AMQP or Kafka integration
 configurations should be moved from folder
 ``/etc/cloudstack/management/META-INF/cloudstack/core`` to
 ``/etc/cloudstack/management/META-INF/cloudstack/event``
+
+Guest OS Categories Change
+==========================
+
+The guest operating system categories have been updated in 4.21, resulting in a
+reorganization of the guest operating systems with respect to categories.
+
+If the ``oscategoryid`` functionality for hosts is being used, ensure it is
+pointing to the correct guest operating system category ID.