diff --git a/source/_static/images/ui-custom-plugin.png b/source/_static/images/ui-custom-plugin.png new file mode 100644 index 0000000000..3e59b59864 Binary files /dev/null and b/source/_static/images/ui-custom-plugin.png differ diff --git a/source/adminguide/ui.rst b/source/adminguide/ui.rst index b47e53c35e..5f8594b015 100644 --- a/source/adminguide/ui.rst +++ b/source/adminguide/ui.rst @@ -181,12 +181,30 @@ new, unique value. Basic UI Customization ~~~~~~~~~~~~~~~~~~~~~~ -Users can now customize the CloudStack's user interface by means of a configuration file at /usr/share/cloudstack-management/webapp/config.json which can be used to modify the theme, logos, etc. to align to one's requirement. +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 +logo Changes the logo top-left side image +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. +========== ================================================== + .. parsed-literal:: + "apiBase": "/client/api", + "docBase": "http://docs.cloudstack.apache.org/en/latest", + "appTitle": "CloudStack", + "footer": "Licensed under the Apache License, Version 2.0.", "logo": "assets/logo.svg", "banner": "assets/banner.svg", "error": { @@ -195,15 +213,36 @@ To change the logo, login banner, error page icon, etc. the following details ca "500": "assets/500.png" } -where, - -- logo: changes the logo top-left side image. -- 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. -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: +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: + +============================= ================================================================ +Property Description +============================= ================================================================ +@logo-background-color Changes the logo background color +@project-nav-text-color Changes the navigation menu background color of the project +@project-nav-text-color Changes the navigation menu background color of the project view. +@navigation-background-color Changes the navigation menu background color +@primary-color Changes the major background color of the page (background button, icon hover, etc). +@link-color Changes the link color +@link-hover-color Changes the link hover color +@loading-color Changes the message loading color and page loading bar at the top page +@success-color Changes success state color +@processing-color Changes processing state color. Exp: progress status +@warning-color Changes warning state color +@error-color Changes error state color +@heading-color Changes table header color +@text-color Change in major text color +@text-color-secondary Change of secondary text color (breadcrumb icon) +@disabled-color Disable state color (disabled button, switch, etc) +@border-color-base Change in major border color +@logo-width Change the width of the logo top-left side +@logo-height Change the height of the logo top-left side +@banner-width Changes the width of the login banner +@banner-height Changes the height of the login banner +@error-width Changes the width of the error image +@error-height Changes the height of the error image +============================= ================================================================ .. parsed-literal:: @@ -237,33 +276,6 @@ Customization of themes is also possible, such as, modifying banner width, gener "@error-height": "256px" } -where, - -- @logo-background-color changes the logo background color. -- @project-nav-background-color changes the navigation menu background color of the project. -- @project-nav-text-color changes the navigation menu background color of the project view. -- @navigation-background-color changes the navigation menu background color. -- @navigation-text-color changes the navigation text color. -- @primary-color: changes the major background color of the page (background button, icon hover, etc). -- @link-color changes the link color. -- @link-hover-color changes the link hover color. -- @loading-color changes the message loading color and page loading bar at the top page. -- @success-color: changes success state color. -- @processing-color: changes processing state color. Exp: progress status. -- @warning-color: changes warning state color. -- @error-color: changes error state color. -- @heading-color: changes table header color. -- @text-color: change in major text color. -- @text-color-secondary: change of secondary text color (breadcrumb icon). -- @disabled-color: disable state color (disabled button, switch, etc). -- @border-color-base: change in major border color. -- @logo-width: change the width of the logo top-left side. -- @logo-height: change the height of the logo top-left side. -- @banner-width: changes the width of the login banner. -- @banner-height: changes the height of the login banner. -- @error-width: changes the width of the error image. -- @error-height: changes the height of the error image. - Some assorted primary theme colours: - Blue: #1890FF @@ -273,8 +285,177 @@ Some assorted primary theme colours: - Green: #52C41A - Purple: #722ED1 -Advanced Customisation -~~~~~~~~~~~~~~~~~~~~~~ +Contextual help documentation URLs can be customized with the help of `docBase` and `docHelpMappings` properties. +To override a particular documentation URL, a mapping can be added for the URL path in the config. A documentation URL is formed by combining the `docBase` URL base and a path set in the source code. Adding a mapping for any particular path in the configuration will result in generating documetation URL with overridden path. +By default, `docHelpMappings` lists all existing documentation URL suffixes, mapped to themselves, in the configuration file that are used in the code. + +.. parsed-literal:: + + { + ... + "docHelpMappings": { + "adminguide/accounts.html": "adminguide/accounts.html", + "adminguide/accounts.html#domains": "adminguide/accounts.html#domains", + "adminguide/accounts.html#roles": "adminguide/accounts.html#roles", + "adminguide/accounts.html#users": "adminguide/accounts.html#users", + "adminguide/accounts.html#using-an-ldap-server-for-user-authentication": "adminguide/accounts.html#using-an-ldap-server-for-user-authentication", + "adminguide/events.html": "adminguide/events.html", + "adminguide/events.html#deleting-and-archiving-events-and-alerts": "adminguide/events.html#deleting-and-archiving-events-and-alerts", + "adminguide/hosts.html#disabling-and-enabling-zones-pods-and-clusters": "adminguide/hosts.html#disabling-and-enabling-zones-pods-and-clusters", + "adminguide/hosts.html#kvm-rolling-maintenance": "adminguide/hosts.html#kvm-rolling-maintenance", + "adminguide/hosts.html#maintaining-hypervisors-on-hosts": "adminguide/hosts.html#maintaining-hypervisors-on-hosts", + "adminguide/hosts.html#out-of-band-management": "adminguide/hosts.html#out-of-band-management", + "adminguide/hosts.html#removing-hosts": "adminguide/hosts.html#removing-hosts", + "adminguide/installguide/configuration.html#adding-a-cluster": "adminguide/installguide/configuration.html#adding-a-cluster", + "adminguide/installguide/configuration.html#adding-a-host": "adminguide/installguide/configuration.html#adding-a-host", + "adminguide/installguide/hosts.html#disabling-and-enabling-zones-pods-and-clusters": "adminguide/installguide/hosts.html#disabling-and-enabling-zones-pods-and-clusters", + "adminguide/management.html#administrator-alerts": "adminguide/management.html#administrator-alerts", + "adminguide/management.html#reporting-cpu-sockets": "adminguide/management.html#reporting-cpu-sockets", + "adminguide/networking_and_traffic.html#acl-on-private-gateway": "adminguide/networking_and_traffic.html#acl-on-private-gateway", + "adminguide/networking_and_traffic.html#adding-a-private-gateway-to-a-vpc": "adminguide/networking_and_traffic.html#adding-a-private-gateway-to-a-vpc", + "adminguide/networking_and_traffic.html#adding-a-security-group": "adminguide/networking_and_traffic.html#adding-a-security-group", + "adminguide/networking_and_traffic.html#adding-a-virtual-private-cloud": "adminguide/networking_and_traffic.html#adding-a-virtual-private-cloud", + "adminguide/networking_and_traffic.html#advanced-zone-physical-network-configuration": "adminguide/networking_and_traffic.html#advanced-zone-physical-network-configuration", + "adminguide/networking_and_traffic.html#basic-zone-physical-network-configuration": "adminguide/networking_and_traffic.html#basic-zone-physical-network-configuration", + "adminguide/networking_and_traffic.html#configure-guest-traffic-in-an-advanced-zone": "adminguide/networking_and_traffic.html#configure-guest-traffic-in-an-advanced-zone", + "adminguide/networking_and_traffic.html#configuring-a-virtual-private-cloud": "adminguide/networking_and_traffic.html#configuring-a-virtual-private-cloud", + "adminguide/networking_and_traffic.html#configuring-network-access-control-list": "adminguide/networking_and_traffic.html#configuring-network-access-control-list", + "adminguide/networking_and_traffic.html#creating-acl-lists": "adminguide/networking_and_traffic.html#creating-acl-lists", + "adminguide/networking_and_traffic.html#creating-and-updating-a-vpn-customer-gateway": "adminguide/networking_and_traffic.html#creating-and-updating-a-vpn-customer-gateway", + "adminguide/networking_and_traffic.html#creating-an-internal-lb-rule": "adminguide/networking_and_traffic.html#creating-an-internal-lb-rule", + "adminguide/networking_and_traffic.html#creating-a-vpn-connection": "adminguide/networking_and_traffic.html#creating-a-vpn-connection", + "adminguide/networking_and_traffic.html#creating-a-vpn-gateway-for-the-vpc": "adminguide/networking_and_traffic.html#creating-a-vpn-gateway-for-the-vpc", + "adminguide/networking_and_traffic.html#enabling-or-disabling-static-nat": "adminguide/networking_and_traffic.html#enabling-or-disabling-static-nat", + "adminguide/networking_and_traffic.html#load-balancing-across-tiers": "adminguide/networking_and_traffic.html#load-balancing-across-tiers", + "adminguide/networking_and_traffic.html#releasing-an-ip-address-alloted-to-a-vpc": "adminguide/networking_and_traffic.html#releasing-an-ip-address-alloted-to-a-vpc", + "adminguide/networking_and_traffic.html#reserving-public-ip-addresses-and-vlans-for-accounts": "adminguide/networking_and_traffic.html#reserving-public-ip-addresses-and-vlans-for-accounts", + "adminguide/networking_and_traffic.html#restarting-and-removing-a-vpn-connection": "adminguide/networking_and_traffic.html#restarting-and-removing-a-vpn-connection", + "adminguide/networking_and_traffic.html#security-groups": "adminguide/networking_and_traffic.html#security-groups", + "adminguide/networking_and_traffic.html#setting-up-a-site-to-site-vpn-connection": "adminguide/networking_and_traffic.html#setting-up-a-site-to-site-vpn-connection", + "adminguide/networking_and_traffic.html#updating-and-removing-a-vpn-customer-gateway": "adminguide/networking_and_traffic.html#updating-and-removing-a-vpn-customer-gateway", + "adminguide/networking.html#creating-a-new-network-offering": "adminguide/networking.html#creating-a-new-network-offering", + "adminguide/networking.html#network-offerings": "adminguide/networking.html#network-offerings", + "adminguide/networking.html#network-service-providers": "adminguide/networking.html#network-service-providers", + "adminguide/projects.html": "adminguide/projects.html", + "adminguide/projects.html#accepting-a-membership-invitation": "adminguide/projects.html#accepting-a-membership-invitation", + "adminguide/projects.html#adding-project-members-from-the-ui": "adminguide/projects.html#adding-project-members-from-the-ui", + "adminguide/projects.html#creating-a-new-project": "adminguide/projects.html#creating-a-new-project", + "adminguide/projects.html#sending-project-membership-invitations": "adminguide/projects.html#sending-project-membership-invitations", + "adminguide/projects.html#suspending-or-deleting-a-project": "adminguide/projects.html#suspending-or-deleting-a-project", + "adminguide/reliability.html#ha-for-hosts": "adminguide/reliability.html#ha-for-hosts", + "adminguide/service_offerings.html#compute-and-disk-service-offerings": "adminguide/service_offerings.html#compute-and-disk-service-offerings", + "adminguide/service_offerings.html#creating-a-new-compute-offering": "adminguide/service_offerings.html#creating-a-new-compute-offering", + "adminguide/service_offerings.html#creating-a-new-disk-offering": "adminguide/service_offerings.html#creating-a-new-disk-offering", + "adminguide/service_offerings.html#creating-a-new-system-service-offering": "adminguide/service_offerings.html#creating-a-new-system-service-offering", + "adminguide/service_offerings.html#modifying-or-deleting-a-service-offering": "adminguide/service_offerings.html#modifying-or-deleting-a-service-offering", + "adminguide/service_offerings.html#system-service-offerings": "adminguide/service_offerings.html#system-service-offerings", + "adminguide/storage.html#creating-a-new-volume": "adminguide/storage.html#creating-a-new-volume", + "adminguide/storage.html#id2": "adminguide/storage.html#id2", + "adminguide/storage.html#primary-storage": "adminguide/storage.html#primary-storage", + "adminguide/storage.html#resizing-volumes": "adminguide/storage.html#resizing-volumes", + "adminguide/storage.html#secondary-storage": "adminguide/storage.html#secondary-storage", + "adminguide/storage.html#uploading-an-existing-volume-to-a-virtual-machine": "adminguide/storage.html#uploading-an-existing-volume-to-a-virtual-machine", + "adminguide/storage.html#working-with-volumes": "adminguide/storage.html#working-with-volumes", + "adminguide/storage.html#working-with-volume-snapshots": "adminguide/storage.html#working-with-volume-snapshots", + "adminguide/systemvm.html": "adminguide/systemvm.html", + "adminguide/systemvm.html#upgrading-virtual-routers": "adminguide/systemvm.html#upgrading-virtual-routers", + "adminguide/systemvm.html#virtual-router": "adminguide/systemvm.html#virtual-router", + "adminguide/templates.html": "adminguide/templates.html", + "adminguide/templates.html#attaching-an-iso-to-a-vm": "adminguide/templates.html#attaching-an-iso-to-a-vm", + "adminguide/templates.html#exporting-templates": "adminguide/templates.html#exporting-templates", + "adminguide/templates.html#id10": "adminguide/templates.html#id10", + "adminguide/templates.html#sharing-templates-with-other-accounts-projects": "adminguide/templates.html#sharing-templates-with-other-accounts-projects", + "adminguide/templates.html#uploading-templates-and-isos-from-a-local-computer": "adminguide/templates.html#uploading-templates-and-isos-from-a-local-computer", + "adminguide/templates.html#uploading-templates-from-a-remote-http-server": "adminguide/templates.html#uploading-templates-from-a-remote-http-server", + "adminguide/templates.html#working-with-isos": "adminguide/templates.html#working-with-isos", + "adminguide/virtual_machines.html": "adminguide/virtual_machines.html", + "adminguide/virtual_machines.html#affinity-groups": "adminguide/virtual_machines.html#affinity-groups", + "adminguide/virtual_machines.html#backup-offerings": "adminguide/virtual_machines.html#backup-offerings", + "adminguide/virtual_machines.html#change-affinity-group-for-an-existing-vm": "adminguide/virtual_machines.html#change-affinity-group-for-an-existing-vm", + "adminguide/virtual_machines.html#changing-the-vm-name-os-or-group": "adminguide/virtual_machines.html#changing-the-vm-name-os-or-group", + "adminguide/virtual_machines.html#creating-a-new-affinity-group": "adminguide/virtual_machines.html#creating-a-new-affinity-group", + "adminguide/virtual_machines.html#creating-the-ssh-keypair": "adminguide/virtual_machines.html#creating-the-ssh-keypair", + "adminguide/virtual_machines.html#creating-vm-backups": "adminguide/virtual_machines.html#creating-vm-backups", + "adminguide/virtual_machines.html#creating-vms": "adminguide/virtual_machines.html#creating-vms", + "adminguide/virtual_machines.html#delete-an-affinity-group": "adminguide/virtual_machines.html#delete-an-affinity-group", + "adminguide/virtual_machines.html#deleting-vms": "adminguide/virtual_machines.html#deleting-vms", + "adminguide/virtual_machines.html#how-to-dynamically-scale-cpu-and-ram": "adminguide/virtual_machines.html#how-to-dynamically-scale-cpu-and-ram", + "adminguide/virtual_machines.html#importing-backup-offerings": "adminguide/virtual_machines.html#importing-backup-offerings", + "adminguide/virtual_machines.html#moving-vms-between-hosts-manual-live-migration": "adminguide/virtual_machines.html#moving-vms-between-hosts-manual-live-migration", + "adminguide/virtual_machines.html#resetting-ssh-keys": "adminguide/virtual_machines.html#resetting-ssh-keys", + "adminguide/virtual_machines.html#restoring-vm-backups": "adminguide/virtual_machines.html#restoring-vm-backups", + "adminguide/virtual_machines.html#stopping-and-starting-vms": "adminguide/virtual_machines.html#stopping-and-starting-vms", + "adminguide/virtual_machines.html#using-ssh-keys-for-authentication": "adminguide/virtual_machines.html#using-ssh-keys-for-authentication", + "adminguide/virtual_machines.html#virtual-machine-snapshots": "adminguide/virtual_machines.html#virtual-machine-snapshots", + "installguide/configuration.html#adding-a-pod": "installguide/configuration.html#adding-a-pod", + "installguide/configuration.html#adding-a-zone": "installguide/configuration.html#adding-a-zone", + "installguide/configuration.html#add-primary-storage": "installguide/configuration.html#add-primary-storage", + "installguide/configuration.html#add-secondary-storage": "installguide/configuration.html#add-secondary-storage", + "plugins/cloudian-connector.html": "plugins/cloudian-connector.html", + "plugins/cloudstack-kubernetes-service.html": "plugins/cloudstack-kubernetes-service.html", + "plugins/cloudstack-kubernetes-service.html#creating-a-new-kubernetes-cluster": "plugins/cloudstack-kubernetes-service.html#creating-a-new-kubernetes-cluster", + "plugins/cloudstack-kubernetes-service.html#deleting-kubernetes-cluster": "plugins/cloudstack-kubernetes-service.html#deleting-kubernetes-cluster", + "plugins/cloudstack-kubernetes-service.html#kubernetes-supported-versions": "plugins/cloudstack-kubernetes-service.html#kubernetes-supported-versions", + "plugins/cloudstack-kubernetes-service.html#scaling-kubernetes-cluster": "plugins/cloudstack-kubernetes-service.html#scaling-kubernetes-cluster", + "plugins/cloudstack-kubernetes-service.html#starting-a-stopped-kubernetes-cluster": "plugins/cloudstack-kubernetes-service.html#starting-a-stopped-kubernetes-cluster", + "plugins/cloudstack-kubernetes-service.html#stopping-kubernetes-cluster": "plugins/cloudstack-kubernetes-service.html#stopping-kubernetes-cluster", + "plugins/cloudstack-kubernetes-service.html#upgrading-kubernetes-cluster": "plugins/cloudstack-kubernetes-service.html#upgrading-kubernetes-cluster", + "plugins/nuage-plugin.html?#optional-create-and-enable-vpc-offering": "plugins/nuage-plugin.html?#optional-create-and-enable-vpc-offering", + "plugins/nuage-plugin.html?#vpc-offerings": "plugins/nuage-plugin.html?#vpc-offerings", + "plugins/quota.html": "plugins/quota.html", + "plugins/quota.html#quota-credits": "plugins/quota.html#quota-credits", + "plugins/quota.html#quota-tariff": "plugins/quota.html#quota-tariff" + }, + ... + } + +Below example shows configuration changes for custom documentation help URLs: + +By default, docBase is set to `http://docs.cloudstack.apache.org/en/latest` and contextual help on Instances page links to `http://docs.cloudstack.apache.org/en/latest/adminguide/virtual_machines.html`. +To make Instances page link to `http://mycustomwebsite.com/custom_vm_page.html`, docBase can be set to `http://mycustomwebsite.com` and a docHelpMapping can be added for `adminguide/virtual_machines.html` as `custom_vm_page.html`. + +.. parsed-literal:: + + { + ... + "docBase": http://mycustomwebsite.com, + ... + "docHelpMappings": { + "adminguide/virtual_machines.html": "custom_vm_page.html", + "adminguide/templates.html": "custom_templates_page.html" + }, + ... + } + +UI also provides option to show custom plugins for displaying custom HTML pages or HTTP services in an iframe. Such plugins can be listed in the config file using `plugins` property. +Example for adding custom plugins: + +.. parsed-literal:: + + { + ... + plugins: [ + { + "name": "ExamplePlugin", + "icon": "appstore", + "path": "example.html" + }, + { + "name": "ExamplePlugin1", + "icon": "appstore", + "path": "https://cloudstack.apache.org/" + } + ] + ... + } + +`icon` for the plugin can be chosen from Ant Design icons listed at `Icon - Ant Design Vue https://www.antdv.com/components/icon/`_. +For displaying a custom HTML in the plugin, HTML file can be stored in the CloudStack management server's web application directory on the server, i.e., */usr/share/cloudstack-management/webapp* and `path` can be set to the name of the file. For displaying a service or a web page, URL can be set as the `path` of the plugin. + +|ui-custom-plugin.png| + +Advanced UI Customisation +~~~~~~~~~~~~~~~~~~~~~~~~~ The advanced UI customisation is possible only by changing JavaScript based config files which define rules for sections, names, icons, actions and components and by @@ -283,12 +464,20 @@ building the UI from the source available on `github.com/apache/cloudstack require some experience in JavaScript and VueJS, a development and customisation guide in the source repository. +Useful documentations: + +- `VueJS Guide `_ +- `Vue Ant Design `_ +- `UI Developer `_ +- `JavaScript ES6 Reference `_ +- `Introduction to ES6 `_ + + Known Limitations ~~~~~~~~~~~~~~~~~ -The following features are no longer supported or available: +The following features are no longer supported or available in the UI but are still supported at the API level and in the legacy UI: -- Deployment of a basic zone is not supported. However, existing basic zones will continue to be supported as well as all the actions and views of various resources within the existing basic zone. - Support for S3 based secondary storage. - NFS secondary staging storage list/resource view and add/update actions. - SSL certificate for Guest network LB rule. @@ -296,3 +485,6 @@ The following features are no longer supported or available: .. |change-password.png| image:: /_static/images/change-password.png :alt: button to change a user's password + +.. |ui-custom-plugin.png| image:: /_static/images/ui-custom-plugin.png + :alt: Custom plugin shown in UI with navigation