Development Guides Home >> Guide to the Feature Showcase

Guide to the Feature Showcase - The drivers.json File

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. 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. Filenames must be all lowercase letters.

Each Feature Showcase item's hash includes the following items:

Parameter	Type	Description	Possible Values	Example
`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.	`WebPros International, LLC`
`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. 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 `1` — Don'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.	For an example, see the Parameter Examples section below.
`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`.	For an example, see the Parameter Examples section below.
`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. `0` — Don't spotlight.	`0`
`enable`	hash	Optional A hash of information on handling an Enable action. For an example, see the Actions section below.	`static` — Set a static value. `module`, `method`, `params` — Call a module's function with a set of parameters.	For an example, see the Parameter Examples section below.
`disable`	hash	Optional A hash of information on handling a Disable action. For an example, see the Actions section below.	`static` — Set a static value. `module`, `method`, `params` — Call a module's function with a set of parameters.	For an example, see the Parameter examples section below.
`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 an example, see 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. For an example, see the Actions section below.	`static` — Set a static value. `module`, `method`, `params` — Call a module's function with a set of parameters.	For an example, see the Parameter examples section below.
`precheck`	hash	Optional A hash that contains additional information on how to determine whether the Feature Showcase item should be shown. For an example, see the Actions section below.	`static` — Set a static value. `module`, `method`, `params` — Call a module's function with a set of parameters.	For an example, see the Parameter Examples section below.

Parameter examples

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,target,_blank].','https://go.cpanel.net/localedocs')"

"locale.maketext('[asis,cPanel®] does not translate strings. You will need to provide your own translations.')

showcase

"showcase" : {
    "is_recommended" : `0`,
    "is_spotlight_feature" : `0`
}

enable

"enable" : {
    "module" : "Whostmgr::TweakSettings",
    "method" : "set_value",
    "params" : [
        "Main",
        "userdirprotect",
        `1`
    ]
}

disable

"disable" : {
    "module" : "Whostmgr::TweakSettings",
    "method" : "set_value",
    "params" : [
        "Main",
        "userdirprotect",
        `0`
    ]
}

handle_showcase_submission

handle_showcase_submission" : {
    "module" : "Whostmgr::API::`1`::PublicContact",
    "method" : "set_public_contact",
    "params" : [
        {
            "name" : "FORM(public_contact_name)",
            "url" : "FORM(public_contact_url)"
        }
    ]
}

precheck

"precheck" : {
    "module" : "Whostmgr::Store::Product::Example::Util",
    "method" : "precheck",
    "params" : []
}

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

Important:

If you set the readonly parameter to 1, the system disregards the 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.
precheck — The user can run a precheck on 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.