Child pages
  • Guide to the Feature Showcase - The drivers.json File
Skip to end of metadata
Go to start of metadata

Introduction

Warning:

cPanel & WHM displays the Feature Showcase after installation. Because of this, Feature Showcase items can overwrite some settings, like cpanel.config file contents.

The Feature Showcase system uses the drivers.json file to define Feature Showcase items.

Note:

  • We introduced the drivers.json file method in cPanel & WHM version 74.
  • To remove a Feature Showcase item, remove the appropriate drivers.json file from the /usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ directory.
  • If you want the item to do something that cPanel & WHM doesn't include, write your own custom module with the function.

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

The /usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/ directory contains individual drivers.json files, where drivers is the name of the object driver.

Note:

Filenames must be all lowercase letters.

Each feature showcase item's hash includes the following items:

ParameterTypeDescriptionPossible valuesExample

spec_version

integer

Required

The specification version that the item uses.

2 is the only possible value.2

meta

hash

A hash that contains metadata for the item.

A hash that contains these parameters:

  • meta_version
  • content
  • showcase

auto_enable

Boolean

Whether the system automatically enables the item for new installations.

This parameter defaults to 0.

The meta hash includes this parameter.

Note:

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

  • 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 item's author.

The meta hash includes this hash.

A hash that contains these 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, L.L.C.

url

string

A URL to display as the More Information link.

The content hash includes this parameter.

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

name

hash

A hash of display name information for 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 item's display name.

The name hash includes this parameter.

This parameter defaults to the long parameter's value.

Note:

We recommend setting this value to 30 characters or less. This avoids overlap in the user interface.

A valid string. Example Driver

long

string

Required

A long version of the 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 item.

The content hash includes this parameter.

  • 0 — Display.
  • 1Don't display.
1

first_appears_in

integer

Required

The first version of cPanel & WHM to display the item.

The content hash includes this parameter.

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

last_appears_in

integer

Required

The last version of cPanel & WHM to display the item.

The content hash includes this parameter.

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

abstract

string

A description that appears if the locale system can't 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 the item.

The content hash includes this parameter.

A valid positive integer.1

locale_abstract_strings

array

An array of localized strings from the description of the item.

The content hash includes this array.

An array of localized text and associated parameters.

For more information, read our Guide to Locales documentation.


 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 to recommend or spotlight the item.

The meta hash contains this hash.

Note:

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

  • A hash containing the is_recommended and is_showcase_feature parameters.
  • -1 — 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 recommend the item.

The showcase hash contains this parameter.

This parameter defaults to 0.

Note:

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

  • 1 — Recommend.
  • 0 — Do not recommend.
0

is_spotlight_feature

Boolean

Whether to spotlight the item.

The showcase hash contains this parameter.

This parameter defaults to 0.

  • 1 — Spotlight.
  • 0Don't spotlight.
0

enable

hash

Optional

A hash of information on handling an Enable action.

For more information, read the Actions section below.

  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.
 Click here to expand...
"enable" : {
    "module" : "Whostmgr::TweakSettings",
    "method" : "set_value",
    "params" : [
        "Main",
        "userdirprotect",
        1
    ]
}

disable

hash

Optional

A hash of information on handling a Disable action.

For more information, read the Actions section below.

  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.
 Click here to expand...
"disable" : {
    "module" : "Whostmgr::TweakSettings",
    "method" : "set_value",
    "params" : [
        "Main",
        "userdirprotect",
        0
    ]
}

set_default

Boolean

Optional

Whether to set Enable or Disable as the default value.

This parameter defaults to a value of 0.

Note:

  • The value of the readonly parameter must be 0 for this parameter to function.
  • For more information, read the Actions section below.
  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.

Note:

We usually recommend enabling new features. To do this, set the set_default parameter to a value of 1.

1

handle_showcase_submission

hash

Optional

A hash of information on handling form data entry.

  • static — Set a static value.
  • module, method, params — Call a module's function with a set of parameters.
 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)"
        }
    ]
}

Actions

You can offer users a range of actions to perform in each item. Then, the system can determine additional actions for each user action.

User actions

Note:

If you set the readonly parameter to 1, the system disregards Enable (enable), Disable (disable), and Set Default (set_default) actions.

There are several actions to use:

  • enable — The user enables an item.
  • disable — The user disables an item.
    • set_default — Sets either the enable or disable options to the default value.
  • handle_showcase_submission — The user fills out a form for the item.

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

Returns

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

  • enable and disable — Return a value of 1 for success and 0 for failure.
  • set_default — Return a value of 0 for backwards compatibility with version 1.
  • handle_showcase_submission — Return the form response.

Installation and update behavior

Feature showcase items can perform differently on new installations and upgrades.

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

  • The background JSON driver file must contain an auto_enable parameter with a value of 1. This will automatically enable the item for new installations.
  • The activation or configuration JSON driver file must contain:
    • An auto_enable parameter with a value of 0
    • The disable parameter.
    • The set_default parameter. 
    The item will appear for upgraded systems and override the background item.