Page tree
Skip to end of metadata
Go to start of metadata

Overview

The Feature Showcase advertises newly-released features available to WHM users. The interface appears when the root user or a root-enabled WHM user logs in the first time after they install an update to their server.

The Feature Showcase divides the showcase items into three sections:

  1. Showcased Items — Top of the list. Reserved for big or very important changes.
  2. Recommended Items — Items that cPanel, Inc. recommends. cPanel & WHM usually enabled these items, but not always.
  3. New Items — Everything else that we advertise in this release.

Whether a feature showcase item appears and what it contains depends on which items the user has previously seen and the action they took. If no new feature showcase items exist, the Feature Showcase interface does not appear.

Versions

In cPanel & WHM version 74 and later, the Feature Showcase system uses the drivers.json file method to define Feature Showcase items.

Types of showcase items

The Feature Showcase supports the following types of items:

TypeDescriptionImportant parameter settings
Announcements

These showcase items announce a new feature. They do not allow the user to enable or disable that feature, and they do not allow the user to configure a setting.

 Click here to see an example.
{
    "spec_version" : 2,
    "meta" : {
        "auto_enable" : 0,
        "meta_version" : 2,
        "content" : {
            "vendor" : "cPanel, Inc.",
            "url"  : "https://www.cpanel.net/",
            "name" : {
                "short"  : "Example Driver",
                "long"   : "Example Driver for Developer Usage"
            },  
            "readonly" : 1,
            "first_appears_in" : "74",
            "last_appears_in" : "78",
            "abstract" : "An example driver for developers to emulate.",
            "version" : 1,
            "locale_abstract_strings" : [
                "locale.maketext('An example driver for developers to emulate.')",
                "locale.maketext('Comes packed with meta examples that use cPanel’s localization system: [output,url,_1,Cpanel::Locale].','https://go.cpanel.net/localedocs')",
                "locale.maketext('[asis,cPanel®] does not translate strings. You will need to provide your own translations.')"
            ]     
        },  
        "showcase" : {
            "is_recommended" : 0,
            "is_spotlight_feature" : 0
        } 
    }     
} 
"readonly":1
"auto_enable":0

Background

These showcase items do not appear on the Feature Showcase interface. They automatically enable a feature for new system installations.

 Click here to see an example.
{
    "spec_version" : 2,
    "meta" : {
        "auto_enable" : 1,
        "meta_version" : 2,
        "content" : {
            "vendor" : "cPanel, Inc.",
            "url" : "https://www.cpanel.net/",
            "name" : {
                "short" : "Example Driver",
                "long" : "Example Driver for Developer Usage"
            },  
            "readonly" : 0,
            "first_appears_in" : "74",
            "last_appears_in" : "78",
            "abstract" : "An example driver for developers to emulate.",
            "version" : 1,
            "locale_abstract_strings" : [
                "locale.maketext('An example driver for developers to emulate.')",
                "locale.maketext('Comes packed with meta examples that use cPanel’s localization system: [output,url,_1,Cpanel::Locale].','https://go.cpanel.net/localedocs')",
                "locale.maketext('[asis,cPanel®] does not translate strings. You will need to provide your own translations.')"
             ]   
        },
        "showcase" : -1
    }, 
    "enable" : {
        "module" : "Whostmgr::TweakSettings",
        "method" : "set_value",
        "params" : [
            "Main",
            "userdirprotect",
            1
        ]
    }  
} 

"auto_enable":1
"showcase
": -1
"enable": (something)

Activation

These showcase items announce a new feature and allow the user to enable or disable that feature. They do not allow the user to configure a setting. 

Activation items must also include driver code to handle the activation and configuration of the feature.

 Click here to see an example.
{
    "spec_version" : 2,
    "meta" : {
        "auto_enable" : 1,
        "meta_version" : 2,
        "content" : {
            "vendor" : "cPanel, Inc.",
            "url" : "https://www.cpanel.net/",
            "name" : {
                "short" : "Example Driver",
                "long" : "Example Driver for Developer Usage"
            },  
            "readonly" : 0,
            "first_appears_in" : "74",
            "last_appears_in" : "78",
            "abstract" : "An example driver for developers to emulate.",
            "version" : 1,
            "locale_abstract_strings" : [
                "locale.maketext('An example driver for developers to emulate.')",
                "locale.maketext('Comes packed with meta examples that use cPanel’s localization system: [output,url,_1,Cpanel::Locale].','https://go.cpanel.net/localedocs')",
                "locale.maketext('[asis,cPanel®] does not translate strings. You will need to provide your own translations.')"
            ]  
        },
        "showcase" : {
            "is_recommended" : 0,
            "is_spotlight_feature" : 0        
        }
    },
    "enable" : {
        "module" : "Whostmgr::TweakSettings",
        "method" : "set_value",
        "params" : [
            "Main",
            "userdirprotect",
            1
        ]
    },
    "disable" : {
        "module" : "Whostmgr::TweakSettings",
        "method" : "set_value",
        "params" : [
            "Main",
            "userdirprotect",
            0
        ]
     },
    "set_default" : { 
        "static" : 1 
    }
} 

"readonly":0
"auto_enable":0
"enable": (something)
"disable": (something)

Configuration

These showcase items announce a new feature, allow the user to configure a setting

Configuration items must also include driver code to handle the activation and configuration of the feature.

 Click here to see an example.
{
    "spec_version" : 2,
    "meta" : {
        "auto_enable" : 1,
        "meta_version" : 2,
        "content" : {
            "vendor" : "cPanel, Inc.",
            "url" : "https://www.cpanel.net/",
            "name" : {
                "short" : "Example Driver",
                "long" : "Example Driver for Developer Usage"
            },  
            "readonly" : 0,
            "first_appears_in" : "74",
            "last_appears_in" : "78",
            "abstract" : "An example driver for developers to emulate.",
            "version"  : 1,
            "locale_abstract_strings" : [
                "locale.maketext('An example driver for developers to emulate.')",
                "locale.maketext('Comes packed with meta examples that use cPanel’s localization system: [output,url,_1,Cpanel::Locale].','https://go.cpanel.net/localedocs')",
                "locale.maketext('[asis,cPanel®] does not translate strings. You will need to provide your own translations.')"
            ]     
        },
        "showcase" : {
            "is_recommended" : 0,
            "is_spotlight_feature" : 0
        }
    },
    "handle_showcase_submission" : {
        "module" : "Whostmgr::API::1::PublicContact",
        "method" : "set_public_contact",
        "params" : [
            {
                "name" : "FORM(public_contact_name)",
                "url"  : "FORM(public_contact_url)"
             }
        ]
    }      
}     
"readonly":0
"auto_enable":0
"handle_showcase_submission": (something)

The Cpanel/Config/ConfigObj/Driver/drivers.json files

The /usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ directory contains individual drivers.json files in JSON format that define each individual feature showcase item, where drivers represents the name of the ObjectDriver.

Note:

The drivers.json filename must contain all lowercase letters.

Each feature showcase item's hash uses the following format:

ParameterTypeDescriptionPossible valuesExample

spec_version

integer

Required

The specification version that the feature showcase item uses.

2 is the only possible value.2

meta

hash

A hash that contains metadata information for the feature showcase item.

A hash that contains the following parameters:

  • meta_version
  • content
  • showcase

auto_enable

Boolean

Whether the system automatically enables the feature showcase item for new system installations.

Note:

If you set the value of this parameter to 1, you must replace the showcase hash with an integer value of -1 for it to function.

This parameter defaults to 0.

The meta hash includes this parameter.

  • 1 — Default enabled.
  • 0 — Default disabled.
0

meta_version

integer

Required

The specification version that the metadata uses.

The meta hash includes this parameter.

2 is the only possible value.2

content

hash

A hash that contains information about the feature showcase item's author.

The meta hash includes this hash.

A hash that contains the following parameters:

  • vendor
  • url
  • name
  • readonly
  • first_appears_in
  • last_appears_in
  • abstract
  • version
  • locale_abstract_strings
  • showcase

vendor

string

The vendor's name.

The content hash includes this parameter.

A valid string.cPanel, Inc.

url

string

A URL which the feature showcase item will display as the More Information link.

The content hash includes this parameter.

A valid URL.http://www.cpanel.net/

name

hash

A hash that contains information about the display name of the feature showcase item.

The content hash includes this hash.

A hash that contains the short and long parameters.

short

string

A short version of the feature showcase item's display name.

The name hash includes this parameter.

This parameter defaults to the long parameter's value.

Note:

We recommend that you set this value to 30 characters or less to avoid overlap in the user interface.

A valid string. Example Driver

long

string

Required

A long version of the feature showcase item's display name.

The name hash includes this parameter.

A valid string. Example Driver for Developer Usage

readonly

Boolean

Whether to display the Enable and Disable options for this feature showcase item.

The content hash includes this parameter.

  • 1 — Do not display the enable or disable options.
  • 0 — Display the enable and disable options.
1

first_appears_in

integer

Required

The first version in which cPanel & WHM will display this feature showcase item.

The content hash includes this parameter.

A valid even integer that corresponds to a cPanel & WHM main release.74

last_appears_in

integer

Required

The last version in which cPanel & WHM will display this feature showcase item.

The content hash includes this parameter.

A valid even integer that corresponds to a cPanel & WHM main release.78

abstract

string

A brief description of the feature showcase item that appears if the localization engine cannot process the locale_abstract_strings and locale_abstract_params parameters.

The content hash includes this parameter.

A valid string. An example driver for developers to emulate.

version

integer

The version of this feature showcase item.

The content hash includes this parameter.

A valid positive integer.1

locale_abstract_strings

array

An array that lists localized strings that appear in the description of the feature showcase item.

The content hash includes this array.

An array of strings that contain localization markups and their associated parameters which the system will interpret. For more information, read the Localization format section of this document.
 Click here to expand...
"locale.maketext('An example driver for developers to emulate.')",
"locale.maketext('Comes packed with meta examples that use cPanel’s localization system: [output,url,_1,Cpanel::Locale].','https://go.cpanel.net/localedocs')",
"locale.maketext('[asis,cPanel®] does not translate strings. You will need to provide your own translations.')

showcase

hash or integer

Whether we recommend or spotlight the feature showcase item?

The meta hash contains this hash.

Note:

If you set the auto_enable parameter to a value of 1, you must set this parameter to a value of -1.

  • A hash that contains the is_recommended and is_showcase_feature parameters.
  • -1 — If the value of the auto_enable parameter is 1.
 Click here to expand...
                 "showcase" : {
                     "is_recommended" : 0,
                     "is_spotlight_feature" : 0 
                 }   

is_recommended

Boolean

Whether to mark the feature showcase item with a recommendation.

Note:

If you enable both the is_recommended and is_spotlight_feature parameters, the Feature Showcase uses the is_recommended parameter.

The showcase hash contains this parameter.

This parameter defaults to 0.

  • 1 — Recommend the feature showcase item.
  • 0 — Do not recommend the feature showcase item.
0

is_spotlight_feature

Boolean

Whether to mark the feature showcase item with spotlight formatting.

The showcase hash contains this parameter.

This parameter defaults to 0.

  • 1 — Spotlight the feature showcase item.
  • 0 — Do not spotlight the feature showcase item.
0

enable

hash

Optional

A hash that contains information on how to handle an Enable action on a feature showcase item.

  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.

Read the Actions section of this document.

 Click here to expand...
"enable" : {
    "module" : "Whostmgr::TweakSettings",
    "method" : "set_value",
    "params" : [
        "Main",
        "userdirprotect",
        1
    ]
}

disable

hash

Optional

A hash that contains information on how to handle an Disable action on a feature showcase item.

  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.

Read the Actions section of this document.

 Click here to expand...
"disable" : {
    "module" : "Whostmgr::TweakSettings",
    "method" : "set_value",
    "params" : [
        "Main",
        "userdirprotect",
        0
    ]
}

set_default

Boolean

Optional

Whether to set the enable or disable option as the default value.

Note:

The value of the readonly parameter must be 0 for this parameter to function.

This parameter defaults to a value of 0.

  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.

Read the Actions section of this document.

Note:

Because we usually recommend that a user enable a new feature, you will want to set the set_default parameter to a value of 1.

1

handle_showcase_submission

hash

Optional

A hash that contains information on how to handle form data entry within a feature showcase item.

  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.

Read the Actions section of this document.

 Click here to expand...
"handle_showcase_submission" : {
    "module" : "Whostmgr::API::1::PublicContact",
    "method" : "set_public_contact",
    "params" : [
        {
            "name" : "FORM(public_contact_name)",
            "url" : "FORM(public_contact_url)"
        }
    ]
}

Localization format

The locale_abstract_strings parameter contains all of the text strings to include in the feature showcase item.

  • Every string should begin with the phrase locale.maketext to trigger the Locale system, and they should follow our localization guidelines (for example, asis tags around literal terms.)
  • Include any parameters to process at the end of a string.
  • Remember to use the curly quote character ( ’ ) instead of the single quote character ( ' ) for possessives to avoid conflicts with the beginning and ending of the locale.maketext string.

Actions

You can offer the user a range of actions for the user to perform in each feature showcase item, and then the system can perform actions based on each user action.

The following user actions are available:

  • enable — When the user decides to enable a feature showcase item.
  • disable — When the user decides to disable a feature showcase item.
    • set_default — Set either the enable or disable option to the default value.
  • handle_showcase_submission — When the user fills out a form in the feature showcase item.

Note:

If you set the readonly parameter to 1, the system disregards the Enable, Disable, and Set Default types of user actions.

Within each user action section hash, you can declare system actions to perform.

The following system actions are available:

  • Static — Set a static value when the user selects that action. 
  • Call a function — Call a function within a module with a set of parameters.

For example, you could allow the user to enable a feature that sets a new Tweak Setting to enabled (value of 1) with the following JSON code:

"enable" : {
    "module" : "Whostmgr::TweakSettings",
    "method" : "set_value",
    "params" : ['Mail','my_new_tweak_setting',1]
           },

Warning:

Because cPanel & WHM displays the Feature Showcase after installation, Feature Showcase items can overwrite settings that you preconfigure on servers, such as the cpanel.config file.

Note:

If you want the feature showcase item to perform a function that does not currently exist in cPanel & WHM, you will need to write your own custom module with the function.

Returns

Feature showcase items return different values depending on the type of user action.

  • enable and disable actions return a value of 1 for success and 0 for failure.
  • set_default actions return a value of 0 for backwards compatibility with Version 1.
  • handle_showcase_submission actions return the form response.

New installs vs Upgrades

Situations may occur where you wish for a feature showcase item to perform differently on new installs and upgrades.

To do this, create two separate JSON driver files with the same enable parameter code:

  • The Background type JSON driver file must contain an auto_enable parameter with a value of 1. This will automatically enable that feature showcase item for new installations.
  • The Activation or Configuration type JSON driver file must contain an auto_enable parameter with a value of 0, and appropriate disable and set_default parameters. The feature showcase item will appear for upgraded systems, and it will override the Background type item.

Remove a Feature Showcase item

To remove a Feature Showcase item, simply remove the appropriate drivers.json file from the /user/local/cpanel/ Cpanel/Config/ConfigObj/Driver directory.

How to test the Feature Showcase

To test the Feature Showcase, use the following steps:

  1. Log in to WHM as the root user.
  2. Navigate to:  https://hostname:2087//scripts3/feature_showcase
  3. You should see something that resembles the following screen capture:

Troubleshooting

Log file

The system will send any errors to the /usr/local/cpanel/logs/error_log log file. The following output represents errors that a bad driver may cause:

warn [whostmgr3] The following fatal warnings were in the warning_1 driver:
     The meta->first_appears_in field is missing or invalid.
     You must define either enable and disable overrides or a handle_showcase_submission override for interactive feature showcases.
     The meta->last_appears_in field is missing or invalid.
     The meta->meta_version field is missing or invalid.
The warning_1 driver will not be loaded.

warn [whostmgr10] The following non-fatal warnings were in the warning_1 driver:
     The spec_version field is missing or invalid. The system will assume a v2 driver.
The warning_1 driver will still function, but possibly not as intended.

Useful commands

To display previously-viewed and committed features in the Feature Showcase, enter the following command in the command line:

ls /var/cpanel/activate/features

To display a specific previously-viewed Feature Showcase item, enter the following commands in the command line, where name represents the name of the feature you want to show again:

cd /var/cpanel/activate/features
rm -rf name

To sanity-check your JSON syntax and clean up your formatting, run the following command, where draftdrivername.json represents the name of the driver in progress:

perl -MJSON -e '$j;$/=undef;$j=<>;$d=JSON->new->allow_nonref;print $d->pretty->encode($d->decode($j));'  < draftdrivername.json

To output a command to a file, run the following command, where draftdrivername.json represents the name of the driver in progress and drivername.json is the driver's final name:

perl -MJSON -e '$j;$/=undef;$j=<>;$d=JSON->new->allow_nonref;print $d->pretty->encode($d->decode($j));'  < drivername.json > yourfinaldriver.json

To validate JSON while you use the vim editor, run the following command:

:%!perl -MJSON -e '$j;$/=undef;$j=<>;$d=JSON->new->allow_nonref;print $d->pretty->encode($d->decode($j));'

To view all previously-viewed Feature Showcase items, enter the following command in the command line:

rm -rf /var/cpanel/activate/features

Note:

Some Feature Showcase items, such as AutoSSL, depend on other criteria that will appear in the driver’s META module’s showcase() method.

Additional documentation

There is no content with the specified labels

There is no content with the specified labels