Child pages
  • Guide to WHM dynamicui Files
Skip to end of metadata
Go to start of metadata

Introduction

Note:

We implemented the WHM dynamicui system in cPanel & WHM version 64. Older versions of cPanel & WHM use the command2 method.


WHM themes use dynamicui files to display icons and groups.This system controls the items that appear in the WHM interface. The dynamicui file for WHM's default theme exists in the /usr/local/cpanel/whostmgr/docroot/themes/x/dynamicui.conf file.

The WHM dynamicui system only controls items in the WHM interface. The cPanel dynamicui system controls items in the cPanel interface separately.

Important:

To best match the WHM interface, we strongly recommend that you include the provided headers and footers in all of your custom interfaces. For help to match the WHM interfaces, read our Guide to WHM Plugins - Interfaces documentation and our experimental User Interface Style Guide.


The dynamicui file

The dynamicui files contain data that the system uses to generate groups of feature icons. It stores this data as hashes within a JSON-formatted file. Each hash requires the type parameter, which determines if that hash describes a group, a feature's icon image, a subsection, or raw data. The type parameter defaults to image.

For example, the Tweak Settings icon exists within the Server Configuration group, and displays as a text link within that group in the WHM interface's side navigation menu. The dynamicui.conf file contains a group hash for the Server Configuration group, an image hash for the Tweak Settings feature, and could contain subitem hashes or raw hashes for associated content.

The four different types of hash require different additional parameters:

  • group — A subsection of the WHM Home interface that displays a group of features. group hashes can include the following additional parameters:
    • acl
    • dnsonly_ok
    • file
    • group
    • groupdesc
    • grouporder
    • imgtype
    • searchtext
    • subtype
    • target
  • image — An individual WHM feature. image hashes can include the following additional parameters:
    • acl
    • description
    • dnsonly_ok
    • file
    • group
    • imgtype
    • itemdesc
    • itemorder
    • searchtext
    • subtype
    • target
    • url
    • role
    • service
  • subitem — A subsection of an individual WHM feature. subitem hashes can include the following additional parameters:
    • acl
    • breadcrumb
    • dnsonly_ok
    • file
    • group
    • itemdesc
    • parent
    • searchtext
    • target
    • url
  • raw — Contains raw data for template directives.
    • itemdesc

Hash type parameters

For more details about each dynamicui file hash type's parameters, select that hash's tab:

Parameters

A dynamicui file group hash contains the following parameters:

ParameterTypeDescriptionPossible ValuesExample
typestring

The hash's type.

group

group
aclstring

The required Access Control Lists (ACLs) for the group.

  • Only WHM users who possess the specified ACLs can view or use the item.
  • Server owners can configure users' ACLs in WHM's Edit Reseller Nameservers and Privileges interface (WHM >> Home >> Resellers >> Edit Reseller Nameservers and Privileges).


  • ACL= and a comma-separated list of one or more valid ACLs, to restrict access to the group.

    Note:

    For a complete list of available ACLs, read our Guide to WHM Plugins - ACL Reference Chart documentation.

  • A blank value — Allow all WHM users access to the group.
ACL=all
dnsonly_okstring

The group's status for cPanel DNSONLY servers.

  • dns — The group appears on cPanel DNSONLY servers.
  • A blank value — The group does not appear on cPanel DNSONLY servers.
dns
filestring

The icon file to display for the group.

A valid .png or .svg image file, relative to the theme's icon directory.

Note:

Icons for any WHM plugins exist separately from the server's theme. For more information, read our Guide to WHM Plugins - Plugin Files documentation.

feature_name.png
groupstring

The group name.

A valid string.

group_name
groupdescstring

The group's display name.


A valid string.

Note:

You can localize this string to display it in the user's preferred language in the WHM interface. For more information, read our Guide to Locales documentation.

$LANG{'Group Name'}
grouporderinteger

The group's display order in the WHM interface.

A positive integer that indicates the order in which the WHM interface displays the group. Lower values appear at the top of the interface.1
imgtypestring

The image type to use for the group or feature.

icon is the only possible value.icon
searchtextstring

A list of search terms for the group.

A space-separated list of strings.search keywords
subtypestring

The icon type to use.

img is the only possible value.img
targetstring

The area of the interface in which the group.

A valid HTML <a> target attribute.

_blank

Example

A dynamicui file group hash will resemble the following information:

   {
      "type" : "group",
      "acl" : "",
      "dnsonly_ok" : "dns",
      "file" : "group_icon.png",
      "group" : "group_name",
      "groupdesc" : "$LANG{'Group Name'}",
      "grouporder" : 1,
      "imgtype" : "icon",
      "searchtext" : "search keywords",
      "subtype" : "img",
      "target" : "mainFrame" }
  

Parameters

A dynamicui file image hash contains the following parameters:

ParameterTypeDescriptionPossible ValuesExample
typestring

The hash's type.

image

image
aclstring

The required Access Control Lists (ACLs) for the group, feature, or subitem.

  • Only WHM users who possess the specified ACLs can view or use the item.
  • Server owners can configure users' ACLs in WHM's Edit Reseller Nameservers and Privileges interface (WHM >> Home >> Resellers >> Edit Reseller Nameservers and Privileges).


  • ACL= and a comma-separated list of one or more valid ACLs, to restrict access to the feature.

    Note:

    For a complete list of available ACLs, read our Guide to WHM Plugins - ACL Reference Chart documentation.

  • A blank value — Allow all WHM users access to the feature.
ACL=all
descriptionstring

A description of the feature. The system displays this description when the feature appears on the WHM Home interface.

Note:

We added this parameter in cPanel & WHM version 76.

A valid string.

Note:

You can localize this string to display it in the user's preferred language in the WHM interface. For more information, read our Guide to Locales documentation.

 Click here to view ...
View and manage reseller accounts on your server. Resellers manage other [asis,cPanel] accounts and can access [asis,cPanel].
dnsonly_okstring

The feature's status for cPanel DNSONLY servers.

  • dns — The feature appears on cPanel DNSONLY servers.
  • A blank value — The feature does not appear on cPanel DNSONLY servers.
dns
filestring

The icon file to display for the feature.

A valid .png or .svg image file, relative to the theme's icon directory.

Note:

Icons for any WHM plugins exist separately from the server's theme. For more information, read our Guide to WHM Plugins - Plugin Files documentation.

feature_name.png
groupstring

The group in which the item appears.

The group value from an existing group hash.

group_name
imgtypestring

The image type to use for the feature.

icon is the only possible value.icon
itemdescstring

The feature's display name.

  • A valid string.

    Note:

    You can localize this string to display it in the user's preferred language in the WHM interface. For more information, read our Guide to Locales documentation.

  • A valid Template Toolkit directive.
$LANG{'Feature Name'}
itemorderinteger

The feature's display order within its group.

A positive integer that indicates the order in which the feature appears in its group. Lower values appear earlier in the group.1
rolestring or hash

The icon only appears in the interface if the server configuration uses this role. For more information about roles and server configurations, read our How to Use Server Profiles documentation.

Warning:

Do not edit this parameter. The server creates this parameter automatically, and we do not support customizations.

Note:

We added this parameter in cPanel & WHM version 76.

  • A valid server profile role.

    Note:

    For a complete list of roles, read the Module Name column of the Roles section of our How to Use Server Profiles documentation.

  • A JSON hash that contains the match parameter and the roles array.

{
        "match" : "any" ,
        "roles" : [
            "MailSend" ,
            "MailLocal"
        ]
    } ,

match

string

Whether to require all roles in the roles parameter to match the server's roles or any of them.

The role hash contains this parameter.

  • any — Require the server to match all roles in the roles parameter to display the feature. (OR condition)
  • all — Require the server to match all roles in the roles parameter to display the feature. (AND condition)
any

roles

array

An array of roles.

The role hash contains this parameter.

An array that contains one or more role names.

"MailSend" , "MailLocal"
searchtextstring

A list of search terms for the feature.

A space-separated list of strings.search keywords
servicestring or hash

The icon only appears in the interface if the server has the service enabled .

Warning:

Do not edit this parameter. The server creates this parameter automatically, and we do not support customizations.

Note:

We added this parameter in cPanel & WHM version 76.


  • A valid cPanel Service Daemon.

    Note:

    For a complete list of service daemons, read our cPanel Service Daemons documentation.

  • A JSON hash that contains the match parameter and services array.
mysql

match

string

Whether to require all services in the services parameter to match enabled services on the server or any of them.

The service hash contains this parameter.

  • any — Require the server to match all services in the services parameter to display the feature. (OR condition)
  • all — Require the server to match all services in the services parameter to display the feature. (AND condition)
any

services

string

An array of services.

The service hash contains this parameter.

An array that contains one or more service names. "mysql" , "ftp"
subtypestring

The icon type to use.

img is the only possible value.img
targetstring

The area of the interface in which the feature appears.

A valid HTML <a> target attribute.

_blank
urlstring

The location of the feature's interface.

A valid path, relative to the /usr/local/cpanel/ directory./example_plugin/feature_name

Example

A dynamicui file text hash will resemble the following information:

   {
      "type" : "image",
      "acl" : "ACL=all",
      "description" : "$LANG{'This is my interface. There are many like it, but this is mine.'}"
      "dnsonly_ok" : "",
      "file" : "feature_name.png",
      "group" : "group_name",
      "imgtype" : "icon",
      "itemorder" : 2,
      "itemdesc" : "$LANG{'Feature Name'}",
      "searchtext" : "search keywords",
      "subtype" : "img",
      "target" : "mainFrame",
      "url" : "/example_plugin/feature_name",
      "role" : {  
          "match":"any",
          "roles":[  
             "MailSend",
             "MailLocal"
          ]
      },
      "service" : "mysql" }
  

Parameters

A dynamicui file subitem hash contains the following parameters:

ParameterTypeDescriptionPossible ValuesExample
typestring

The hash's type.

subitem

subitem
aclstring

The required Access Control Lists (ACLs) for the subitem.

  • Only WHM users who possess the specified ACLs can view or use the item.
  • Server owners can configure users' ACLs in WHM's Edit Reseller Nameservers and Privileges interface (WHM >> Home >> Resellers >> Edit Reseller Nameservers and Privileges).
  • ACL= and a comma-separated list of one or more valid ACLs, to restrict access to the subitem.

    Note:

    For a complete list of available ACLs, read our Guide to WHM Plugins - ACL Reference Chart documentation.

  • A blank value — Allow all WHM users access to the subitem.
ACL=all
breadcrumbstring

The location of a subitem's parent feature. The system uses this value to generate breadcrumbs at the top of each WHM interface.

The subitem's parent feature's url value.

/example_plugin/feature_name
dnsonly_okstring

The subitem's status for cPanel DNSONLY servers.

  • dns — The subitem appears on cPanel DNSONLY servers.
  • A blank value — The subitem does not appear on cPanel DNSONLY servers.
dns
filestring

The icon file to display for the subitem.

A valid .png or .svg image file, relative to the theme's icon directory.

Note:

Icons for any WHM plugins exist separately from the server's theme. For more information, read our Guide to WHM Plugins - Plugin Files documentation.

feature_name.png
groupstring

The group in which the item appears.

The group value from an existing group hash.

group_name
itemdescstring

The subitem's display name.

A valid string.

Note:

You can localize this string to display it in the user's preferred language in the WHM interface. For more information, read our Guide to Locales documentation.

$LANG{'Feature Name'}
parentinteger

The subitem's parent feature's display order in the WHM interface.

The subitem's parent feature's itemorder value.1
searchtextstring

A list of search terms for the subitem.

A space-separated list of strings.search keywords
targetstring

The area of the interface in which the subitem displays.

A valid HTML <a> target attribute.

_blank
urlstring

The location of the subitem's interface.

A valid path, relative to the /usr/local/cpanel/ directory./example_plugin/feature_name

Example

A dynamicui file subitem hash will resemble the following information:

   {
      "type" : "subitem",
      "acl" : "ACL=all",
      "breadcrumb" : "/example_plugin/feature_name",
      "dnsonly_ok" : "",
      "file" : "subitem_name.png",
      "group" : "group_name",
      "itemdesc" : "$LANG{'Subitem Name'}",
      "parent" : "2",
      "searchtext" : "search keywords",
      "target" : "mainFrame",
      "url" : "/example_plugin/feature_name/sub_item" }
  

Parameters

A dynamicui file raw hash contains the following parameters:

ParameterTypeDescriptionPossible ValuesExample
typestring

The hash's type.

raw — Raw data for template directives.

raw
itemdescstring

The template directive.

A valid Template Toolkit directive.

[% PROCESS 'menu/plugins_list.tmpl' target='mainFrame' -%]

Example

A dynamicui file raw hash will resemble the following information:

   {
      "type" : "raw",
      "itemdesc" : "[% PROCESS 'menu/plugins_list.tmpl' target='mainFrame' -%]" }
  

API control

You can use  WHM API 1's get_available_applications function  to retrieve the contents of  dynamicui  files.

cPanel & WHM version 62 and earlier

In cPanel & WHM version 62 and earlier, the command2 file displayed items for WHM themes.

We removed the /usr/local/cpanel/whostmgr/docroot/themes/x/command2 file from WHM's default theme in cPanel & WHM version 64.